Troubleshooting

Common issues and solutions when working with Traces.

Collection Issues

Collection Stuck in "Pending"

Symptoms: Collection status remains "pending" and never starts.

Possible Causes:

1. Worker is not running
2. Database (pg-boss queue) connection issue
3. Credential validation failed silently

Solutions:

# Run the worker and watch its logs
pnpm --filter @traces/worker dev

# Inspect the queue / collection status in the database
pnpm --filter @traces/database db:studio

The job queue is pg-boss, stored in the pgboss schema of the same Postgres database — there is no Redis queue to ping. If jobs are stuck, confirm the worker shares the same DATABASE_URL as the web app.

Collection Fails with 401 Error

Symptoms: Collection fails with "Unauthorized" or 401 status code.

Possible Causes:

1. Credential expired
2. Credential revoked by user
3. Wrong credential type configured

Solutions:

1. Verify credential is still valid with the platform
2. Ask customer to provide new credentials
3. Check auth configuration in connector matches platform requirements

Collection Fails with 429 Error

Symptoms: Collection fails with "Too Many Requests" or 429 status code.

Possible Causes:

1. Rate limit exceeded
2. Connector rate limit too aggressive
3. Multiple collections running simultaneously

Solutions:

1. Update connector rate limit configuration
2. Reduce page size in pagination config
3. Queue collections instead of running in parallel

Pagination Never Stops

Symptoms: Collection runs indefinitely, fetching the same data repeatedly.

Possible Causes:

1. Stop condition not configured
2. Wrong cursor path
3. API returns same cursor repeatedly

Solutions:

1. Verify stop condition is configured
2. Check cursor path matches actual API response
3. Test pagination manually with API client

Connector Issues

Automated Generation Fails

Symptoms: Connector generation fails during parsing or analysis.

Possible Causes:

1. Invalid or inaccessible documentation URL
2. Unsupported documentation format
3. Anthropic API quota exceeded

Solutions:

1. Verify URL is accessible
2. Try different documentation URL (OpenAPI, Swagger, Postman)
3. Check ANTHROPIC_API_KEY and quota

Dependency Mapping Not Working

Symptoms: Dependent endpoints don't receive values from source endpoints.

Possible Causes:

1. Wrong JSON path configured
2. Source endpoint returns empty data
3. Parameter location mismatch

Solutions:

1. Test source endpoint and verify JSON path
2. Check source endpoint actually returns data
3. Verify parameter location (path, query, body)

Test Endpoint Returns Unexpected Results

Symptoms: Testing endpoint returns different data than expected.

Possible Causes:

1. Test credentials have limited scope
2. Endpoint requires specific parameters
3. Platform API changed

Solutions:

1. Verify credential has required scopes
2. Check if endpoint needs query parameters
3. Review platform API changelog

Authentication Issues

Clerk Sign-in Not Working

Symptoms: Users cannot sign in, redirect loops, or blank pages.

Possible Causes:

1. Incorrect Clerk keys
2. Missing Clerk middleware
3. Domain not configured in Clerk

Solutions:

1. Verify NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY
2. Check middleware.ts is properly configured
3. Add domain to Clerk dashboard

Webhook Verification Failing

Symptoms: Clerk webhooks return 401 or signature mismatch.

Possible Causes:

1. Wrong webhook secret
2. Request body modified before verification
3. Replay attack protection triggered

Solutions:

1. Verify CLERK_WEBHOOK_SECRET matches Clerk dashboard
2. Ensure raw body is used for verification
3. Check server time is synchronized

Database Issues

Migration Failures

Symptoms: pnpm --filter @traces/database db:migrate:dev fails with errors.

Possible Causes:

1. Database connection issue
2. Schema conflict
3. Missing permissions

Solutions:

# Reset database (development only!)
pnpm --filter @traces/database db:migrate:reset

# Generate / apply a new migration
pnpm --filter @traces/database db:migrate:dev

# Check migration status
pnpm --filter @traces/database db:migrate:status

Migrations run against DIRECT_URL (the direct Supabase connection), not the pooled DATABASE_URL. A Tenant or user not found / pooler error usually means DIRECT_URL is missing or wrong.

Prisma Client Out of Sync

Symptoms: TypeScript errors about missing fields or types.

Solutions:

# Regenerate Prisma client
pnpm --filter @traces/database db:generate

# If still failing, clear cache
rm -rf node_modules/.prisma
pnpm install

The generated Prisma client lives at packages/database/generated/prisma and is imported as @traces/database.

Worker Issues

Jobs Not Processing

Symptoms: Jobs added to queue but never processed.

Possible Causes:

1. Worker not running
2. Worker crashed
3. Database connection lost (queue lives in Postgres)

Solutions:

# Start the worker and watch its logs
pnpm --filter @traces/worker dev

Inspect or clear stuck jobs directly in Postgres (the pg-boss tables live in the pgboss schema), e.g. via Prisma Studio or psql:

-- See queued/active jobs
SELECT name, state, count(*) FROM pgboss.job GROUP BY name, state;

Worker Memory Issues

Symptoms: Worker crashes with OOM error.

Possible Causes:

1. Processing very large responses
2. Memory leak in job handler
3. Too many concurrent jobs

Solutions:

1. Reduce page size in pagination
2. Process data in streams instead of loading to memory
3. Reduce worker concurrency

Storage Issues

File Upload Failures

Symptoms: Files fail to upload to R2.

Possible Causes:

1. Invalid R2 credentials
2. Bucket doesn't exist
3. File too large

Solutions:

1. Verify R2 credentials have write permission
2. Create bucket if it doesn't exist
3. Implement multipart upload for large files

Hash Validation Failures

Symptoms: Files show "validation failed" status.

Possible Causes:

1. File corrupted during transfer
2. Hash computed before upload complete
3. Different hash algorithm used

Solutions:

1. Re-download and re-hash the file
2. Ensure upload is complete before hashing
3. Verify SHA-256 is used consistently

Getting Help

If these solutions don't resolve your issue:

1. Check Logs: Review application and worker logs for detailed errors
2. Search Issues: Check GitHub issues for similar problems
3. Ask Community: Post in discussions with error details
4. Contact Support: For urgent production issues

When reporting issues, include:

• Error message and stack trace
• Steps to reproduce
• Environment (development/production)
• Relevant configuration (sanitized)