TeeckIn/Docs

Troubleshooting

Common issues and solutions for AI agent integration.

Authentication Issues

'invalid_client' error

Possible causes:

  • -Client ID or Client Secret was copied incorrectly
  • -Client Secret has been revoked
  • -Agent has been deactivated

Solutions:

  • +Verify TEECKIN_CLIENT_ID starts with "teeckin_agent_"
  • +Verify TEECKIN_CLIENT_SECRET starts with "tcs_"
  • +Check secret status in Settings > Agents > Secrets tab
  • +Create a new secret if the current one was revoked

'Access token expired' error

Possible causes:

  • -Access tokens are valid for 1 hour
  • -Token was not refreshed before expiry

Solutions:

  • +Request a new access token using your client credentials
  • +The MCP server handles this automatically
  • +For API usage, request a new token from /api/oauth/token

'Agent not found' error

Possible causes:

  • -Using credentials from a deleted agent
  • -Agent was never created properly

Solutions:

  • +Create a new agent and save the credentials
  • +Ensure you copy both Client ID and Client Secret when displayed

Timer Issues

Timer won't start

Possible causes:

  • -Another timer is already running
  • -Invalid topic ID
  • -Rate limit exceeded

Solutions:

  • +Check status with teeckin_get_status or GET /api/timer/active
  • +Stop the existing timer before starting a new one
  • +Use teeckin_list_topics to get valid topic IDs

Timer stopped unexpectedly

Possible causes:

  • -Someone stopped it manually in the UI
  • -Server restart (rare)
  • -Agent was deactivated mid-session

Solutions:

  • +Check your time entries to see if it was recorded
  • +Start a new timer if needed

Time entry not appearing

Possible causes:

  • -Timer is still running (not stopped)
  • -Looking at wrong date range
  • -Viewing personal workspace instead of organization

Solutions:

  • +Stop the timer to create the entry
  • +Check the calendar for the correct date
  • +Switch to the correct organization context

Topic Issues

'Topic not found' error

Possible causes:

  • -Using a topic ID that doesn't exist
  • -Topic was deleted
  • -Topic is in a different organization

Solutions:

  • +Refresh your topic list with teeckin_list_topics
  • +Use the updated topic list to get valid IDs

Fuzzy matching picks wrong topic

Possible causes:

  • -Multiple topics have similar names
  • -Query is too ambiguous

Solutions:

  • +Use more specific topic names
  • +Use the full topic ID instead of name
  • +Include the category name: "Backend API Development"

MCP Server Issues (Claude Code)

MCP server not connecting

Possible causes:

  • -Invalid JSON in .mcp.json or .claude/settings.json
  • -Environment variables not set (TEECKIN_CLIENT_ID, TEECKIN_CLIENT_SECRET)
  • -Network connectivity issues
  • -Firewall blocking HTTPS connections

Solutions:

  • +Validate your JSON syntax with a JSON validator
  • +Verify environment variables are exported in your shell profile
  • +Test network connectivity: curl https://api.teeckin.com/mcp
  • +Check that your network allows outbound HTTPS (port 443)

Test the Connection

Verify your credentials work with curl:

bash
# First get an access token
curl -X POST https://api.teeckin.com/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=$TEECKIN_CLIENT_ID" \
  -d "client_secret=$TEECKIN_CLIENT_SECRET"

# Then test the MCP endpoint
curl -X POST https://api.teeckin.com/mcp \
  -H "Authorization: Bearer tat_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Claude doesn't see TeeckIn tools

Possible causes:

  • -MCP server URL not configured in .mcp.json
  • -Claude Code needs restart after config changes
  • -OAuth credentials not configured in env section

Solutions:

  • +Verify mcpServers.teeckin.url is set to https://api.teeckin.com/mcp
  • +Restart Claude Code after editing config files
  • +Check that env section includes TEECKIN_CLIENT_ID and TEECKIN_CLIENT_SECRET

MCP Server Issues (Codex)

MCP server not connecting

Possible causes:

  • -Invalid TOML in ~/.codex/config.toml
  • -Missing [mcp_servers.teeckin] section
  • -TEECKIN_CLIENT_ID or TEECKIN_CLIENT_SECRET not exported in shell

Solutions:

  • +Check TOML syntax - sections need [brackets] and strings need "quotes"
  • +Run npx @teeckin/agent init --codex to regenerate config
  • +Ensure both TEECKIN_CLIENT_ID and TEECKIN_CLIENT_SECRET are exported in your shell profile

Codex doesn't see TeeckIn tools

Possible causes:

  • -Config not in ~/.codex/config.toml (user-level)
  • -Codex needs restart after config changes
  • -env_vars missing OAuth credentials

Solutions:

  • +MCP config should be in ~/.codex/config.toml, not project-level
  • +Restart Codex after editing config.toml
  • +Verify [mcp_servers.teeckin] includes env_vars = ["TEECKIN_CLIENT_ID", "TEECKIN_CLIENT_SECRET"]

Hooks not firing

Possible causes:

  • -hooks.json not in .codex/ directory
  • -Hooks feature not enabled in config.toml
  • -Invalid JSON syntax in hooks.json

Solutions:

  • +Ensure .codex/hooks.json exists in your project root
  • +Add [features] codex_hooks = true to config.toml if required
  • +Validate hooks.json syntax with a JSON validator

Rate Limiting

'Rate limit exceeded' (429) error

Possible causes:

  • -Too many API calls in a short time
  • -Runaway script or loop
  • -Multiple integrations sharing same credentials

Solutions:

  • +Wait 60 seconds and retry
  • +Implement exponential backoff in your integration
  • +Use separate agents or secrets for separate integrations
  • +Cache topic list instead of fetching repeatedly

Rate Limits

  • GET requests: 120 per minute
  • POST/PATCH requests: 30 per minute
  • Timer operations: 10 per minute

Permission Issues

'Permission denied' accessing agent settings

Possible causes:

  • -Not in organization context
  • -Trying to access another member's agents
  • -Organization role doesn't allow access

Solutions:

  • +Switch to the correct organization
  • +You can only manage your own agents (unless admin)
  • +Ask an admin for help with org-wide agent settings

Agent can't access billing/rates

Possible causes:

  • -This is expected behavior - agents have restricted permissions

Solutions:

  • +Agents intentionally cannot see hourly rates or billing data
  • +This is a security feature, not a bug

Personal Agent Issues

'Agents' tab not showing in Settings

Possible causes:

  • -Currently viewing an organization context
  • -Personal agents require personal workspace

Solutions:

  • +Switch to personal workspace (click your name in sidebar, select "Personal")
  • +Personal agents are only visible in personal Settings, not in organizations

'Pro subscription required' error

Possible causes:

  • -Free plan does not include personal agents
  • -Personal agents require Pro or higher

Solutions:

  • +Upgrade to Pro subscription for personal agent access
  • +If using an organization, the org needs Team plan for organization agents

Personal agent tracking to wrong topics

Possible causes:

  • -Agent is accessing organization topics when personal expected
  • -Agent was created in the wrong context

Solutions:

  • +Personal agents access personal topics only
  • +Organization agents access that org's topics only
  • +Create a new agent in the correct context if needed

Getting Help

If you're still having issues:

  • 1.Check that your credentials are valid and the agent is active
  • 2.Try the API directly with curl to isolate the issue
  • 3.Review Claude Code logs for MCP-specific errors
  • 4.Contact support with your error message and steps to reproduce