Troubleshooting

Common issues and how to resolve them. If your problem isn't listed here, check the debugging tools section or reach out for help.

Deploy Failures

Build errors

If your deploy fails during the build step, check the build logs for the specific error:

# View build logs for the latest deploy
telbase logs --build

# View logs for a specific deploy
telbase logs --build --deploy <deploy-id>

Common build failures:

• Missing dependencies — ensure package.json or requirements.txt includes all dependencies. Run npm install or pip install -r requirements.txt locally first to verify.
• TypeScript errors — run npx tsc --noEmit locally to catch type errors before deploying.
• Missing build script — ensure your package.json has a build script.

Deploy timeout

GCP Cloud Run deploys have a 5-minute timeout. If your build exceeds this, try reducing build time by optimizing dependencies or using multi-stage Docker builds. Vercel deploys have longer timeouts and rarely hit this limit.

Provider errors

If the deploy fails with a provider-specific error, the deploy response includes a structured suggestions[] array with recommended fixes. Follow these suggestions or check the provider documentation linked in the error.

How Telbase diagnoses failures

Every failed deploy passes through three diagnosis layers:

1. Pattern matching — 97 known error patterns matched instantly from build and container logs
2. Classification cross-reference — 11 rules connecting detection decisions to failures (e.g., ORM detected as Prisma but drizzle.config.ts found → misclassification)
3. AI diagnosis — an AI agent reads your source code and logs to identify novel failures, returning the root cause with exact file paths, code fixes, and confidence scores

On failure, the deploy response includes an aiDiagnosis field with structured fixes. Your AI agent can auto-apply fixes where autoFixable: true and confidence ≥ 0.7.

Environment Variable Issues

Variables not available at runtime

If your app can't read environment variables after deploy:

• Verify the variable is set: telbase env list
• Check for typos in the key name (keys are case-sensitive)
• Redeploy after setting new variables: telbase deploy
• For client-side variables in Next.js, prefix with NEXT_PUBLIC_

Key format rejected

Variable keys must start with a letter or underscore and contain only alphanumeric characters and underscores. See key format rules.

Sync failures

If variables fail to sync to the provider, compare local and remote state:

# Compare local .env with remote variables
telbase env diff

# Re-push all variables
telbase env push --file .env.production

Domain & DNS Issues

Domain not resolving

DNS changes can take 5–30 minutes to propagate, and up to 48 hours in some cases. Check propagation status:

# Check DNS records
dig CNAME your-domain.com +short

# Verify through Telbase
telbase domain verify your-domain.com

Verification failing

The most common cause is missing or incorrect DNS records. Double-check:

• The CNAME record points to the correct target shown by the CLI
• The TXT verification record is present and matches
• If using Cloudflare, the proxy is disabled (gray cloud / DNS only) during initial setup

SSL certificate not issued

SSL certificates are provisioned automatically after DNS verification. If HTTPS isn't working after verification succeeds, wait a few minutes for the certificate to provision. Run telbase domain list to check certificate status.

Authentication Issues

Token expired

If you see “unauthorized” or “token expired” errors, re-authenticate:

# Re-login
telbase login

# Check current auth status
telbase auth status

Permission denied

If you get “permission denied” errors, check that your account has the correct role in the organization. Org admins can manage all projects; members can only manage their own.

Billing & Limits

Deploy limit reached

Each plan includes a monthly deploy allowance. When exhausted, you can purchase credits for additional deploys (1 credit = 1 extra deploy at $0.10).

# Check remaining deploys and credit balance
telbase status

# Purchase credits
telbase credits add

App or database limit reached

Plan limits restrict how many apps and databases you can create. Options:

• Upgrade your plan for more included resources
• Purchase credits for additional apps (20 credits/$2/mo) or databases (15 credits/$1.50/mo)
• Delete unused projects to free up slots

Credit balance exhausted

When credits run out, overage resources (extra apps, DBs, deploys beyond plan) are paused. Purchase more credits or enable auto-refill:

# Check credit balance
telbase credits

# Enable auto-refill ($10/mo cap)
telbase credits auto-refill enable --amount 10

GitHub Integration

Repository not accessible

If telbase github link can't find your repo, check that the Telbase GitHub App has access to the repository. Go to your GitHub settings → Applications → Telbase to modify repository access.

Push not triggering deploy

If pushes to GitHub aren't triggering deploys:

• Verify the link: telbase github status
• Check you're pushing to the configured deploy branch (default: main)
• Ensure the webhook is active in GitHub → repo Settings → Webhooks

Repository already linked

A repository can only be linked to one project. Unlink it from the other project first:

telbase github unlink

Scheduled Job Issues

Job never runs

Verify the cron expression syntax. Telbase uses standard 5-field cron format (minute hour day month weekday). Test your expression at crontab.guru before deploying. Also confirm the timezone is correct — the default is UTC.

Job auto-paused (circuit breaker)

After 5 consecutive failures, the circuit breaker auto-pauses your schedule and sends an email notification. Check the execution logs to diagnose the issue:

# Check recent execution history
telbase logs --executions

Fix the underlying error, then resume from the dashboard Jobs tab or via the API.

Job exceeds timeout

Each plan has a maximum execution timeout: Starter 5 minutes, Builder 10 minutes, Pro 30 minutes. If your job needs more time, upgrade your plan or optimize the job to complete faster.

Team & Invitations

Invitation pending

If a team invitation shows “pending” and can't be resent, the invitation is still active. The invitee should check their email (including spam folder) for the invitation link.

Team member limit

Free plans are limited to 1 team member. All paid plans (Starter, Builder, Pro) include unlimited team members.

Invitation email not received

Invitation emails are sent from [email protected]. Ask the invitee to check their spam folder and add this address to their allowlist. If the email still doesn't arrive, try removing and re-inviting the team member.

Debugging Tools

Telbase provides several CLI commands for diagnosing issues:

# View runtime logs
telbase logs

# View build logs
telbase logs --build

# Check account status (plan, usage, credits)
telbase status

# List recent deploys with status
telbase deploys

# Check environment variable state
telbase env list

# Compare local and remote env vars
telbase env diff

# Check GitHub integration status
telbase github status

# Check domain and DNS status
telbase domain list

Common Error Codes

When a deploy or operation fails, Telbase returns a structured error code. Here are the most common ones:

Getting Help

If you're stuck, we're here to help:

• Email: [email protected]
• Priority support: available on the Pro plan
• Status page: status.telbase.ai for platform-wide issues