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 a deploy fails during the build, read its build log. Your agent does this itself when it deploys:

# Vercel: the deployments of the linked app, and one deployment's build log
telbase vercel ls
telbase vercel inspect <deployment-url> --logs

# Any app: its deploys, and the build log of the last one
telbase deploys --project my-app
telbase logs --project my-app --build

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.

The app fails after the deploy

Check the app at its Telbase URL, then read its logs. On Vercel they are live only, so follow them while you repeat the request:

telbase logs --project my-app --follow

Telbase refused a command

A refusal names its reason and what to run instead, in a fix field. It is policy, not a glitch: retrying the same call gets the same answer. The common error codes are listed below.

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 --project my-app
• Check for typos in the key name (keys are case-sensitive)
• Values set on the provider apply to the next build: on Vercel, telbase env set rebuilds the live deployment itself; a value added with telbase vercel env add needs a redeploy
• 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

Sign-in expired

If a command says your sign-in has expired or is not valid, sign out and sign in again. Sign out first: an older CLI's telbase login says “Already logged in” while the saved sign-in no longer works.

telbase logout
telbase login

# Check who you are signed in as
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

Telbase does not deploy on push yet. Ask your agent to deploy, or run the app's deploy command (telbase apps info <app> prints it).

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 jobs executions <job>

Fix the underlying error, then run telbase jobs resume <job>.

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:

# Check sign-in, the session, the skills, the Vercel CLI and gcloud
telbase doctor

# View runtime logs
telbase logs --project my-app

# View build logs
telbase logs --project my-app --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 an operation fails or is refused, Telbase returns a structured error code, usually with a fix. 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