Troubleshooting

MCP Connection Issues

Agent cannot connect to the MCP server

Symptom: The AI agent reports "MCP server not available" or "connection refused".

Solutions:

1. OpenCode: Verify the remote URL in ~/.config/opencode/opencode.json points to your Complaintr instance. The path must be /api/mcp.

{
  "mcp": {
    "complaintr": {
      "type": "remote",
      "url": "http://localhost:3000/api/mcp",
      "enabled": true
    }
  }
}

2. Stdio clients: Make sure bun is installed and available in your PATH. Try running bun x @complaintr/mcp-server directly in a terminal to see if it starts.

3. Firewall: If using a remote instance, ensure port 3000 (or your configured port) is accessible from the client machine.

MCP server reports "Application not found"

This happens when the agent calls report_complaint with an appName that does not match any registered application.

Solutions:

• Check the exact spelling (names are case-insensitive but must match exactly)
• Verify the application is registered in your Complaintr dashboard
• Ask the agent to use the exact name from your dashboard

MCP server returns "Too many requests"

You have hit the rate limit (10 requests per minute per IP).

Solutions:

• Wait 60 seconds before retrying
• If this happens frequently, adjust your agent's reporting behavior to batch complaints

Authentication Issues

Cannot sign in with Google

Symptom: "invalid_client" error or redirect loop.

Solutions:

1. Verify GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are correctly set in your .env file
2. Check that the authorized redirect URI matches your instance URL: http://localhost:3000/api/auth/callback/google (or your production URL)
3. Ensure BETTER_AUTH_URL is set to your instance URL (e.g., http://localhost:3000)
4. BETTER_AUTH_SECRET must be a random 64-character string. Generate one with openssl rand -hex 32

Session expires too quickly

Sessions expire after 30 days of inactivity by default. If you are being logged out sooner:

Solutions:

• Clear browser cookies for the Complaintr domain
• Ensure your system clock is accurate (session tokens include timestamps)

Database Issues

Cannot connect to PostgreSQL

Symptom: "ECONNREFUSED" or "role does not exist" errors.

Solutions:

1. Verify PostgreSQL is running: pg_isready
2. Check DATABASE_URL in your .env file matches your PostgreSQL setup
3. If using Docker: docker compose up db -d
4. For local PostgreSQL without Docker: create the role and database:

   psql -U postgres -c "CREATE ROLE complaintr WITH LOGIN PASSWORD 'complaintr';"
   psql -U postgres -c "CREATE DATABASE complaintr OWNER complaintr;"

Migrations fail

Symptom: drizzle-kit errors during migration.

Solutions:

1. Ensure DATABASE_URL is accessible from the directory where you run the command
2. Try bun run db:push for direct schema push (bypasses migration files)
3. Check that your PostgreSQL version is 17 or later

Telegram Bot Issues

Bot does not respond to commands

Symptom: The Telegram bot shows as online but doesn't respond to /start or /report.

Solutions:

1. Verify TELEGRAM_BOT_TOKEN is correctly set in your .env file
2. Check that the telegram-bot process is running: bun --filter @complaintr/telegram-bot dev
3. The bot uses long-polling — ensure the DATABASE_URL is accessible from the bot's process

Cannot link Telegram account

Solution: Send /start to the bot in a private DM. The code expires after 10 minutes. If it expires, send /start again for a new code.

Dashboard Issues

Dashboard shows no data

Symptom: Dashboard loads but shows zeroes and empty states.

Solutions:

1. Ensure you have registered at least one application
2. Check that complaints are being submitted by AI agents
3. Try a broader time range (Weekly/Monthly/All time from the period selector)

Chart does not render

Symptom: The complaint activity chart is missing or blank.

Solution: This can happen if no complaints exist in the selected time period. Try "All time" view or wait for new complaints.

Production Deployment

See the Deployment Guide for production configuration tips.

Environment variables not loading

Symptom: "TELEGRAM_BOT_TOKEN is not set" or similar errors in production.

Solutions:

1. Ensure all required environment variables are set in your deployment environment
2. In Docker Compose, use ${VAR:-default} syntax or .env file
3. The .env file at the project root is read by next.config.ts, drizzle.config.ts, and the Telegram bot