Skip to main content
Quick solutions to common problems.

​
CLI issues

The CLI isn’t in your PATH. Reinstall:
Or with pipx:
Check your setup:
Re-authenticate:
Keys should start with runtm_. Get a new key from app.runtm.com.
If self-hosting, check your API URL:

​
Deploy issues

Auto-fix lockfiles:
Or skip the prompt:
Set the missing secret:
Check what’s being included:
Add large files to .gitignore. Max artifact size is 20MB.
Builds have a 10-minute limit. Common causes:
  • Too many dependencies
  • Large assets being processed
  • Network issues during package install
Try a higher tier:
Your app must respond HTTP 200 at /health (or custom health_path).Test locally:
Check logs:

​
Runtime issues

Check runtime logs:
Common causes:
  • Missing environment variables
  • Wrong port (should match manifest)
  • Unhandled exceptions during init
Upgrade to a higher tier:
If using features.database: true:
  • Ensure your app connects to sqlite:///data/app.db
  • The /data directory is mounted automatically
  • Check for file permission issues in logs
Apps in suspended state take ~1-2 seconds to wake. To reduce this:
  • Minimize startup work
  • Use lazy loading for heavy dependencies
  • Consider performance tier for faster cold starts

​
Self-hosting issues

Find what’s using the port:
Stop the conflicting process or use a docker-compose.override.yml to change ports.
Check PostgreSQL is running:
Check worker logs:
Verify:
  • FLY_API_TOKEN is set in .env
  • Redis is running
  • API is healthy
Migrations run on API startup. To run manually:
Or inside container:
Use a Personal Access Token, not a deploy token:
Deploy tokens (fly tokens create deploy) don’t have Logs API access.

​
Validation errors

Validate your runtm.yaml:
Common issues:
  • Missing required fields (name, template, runtime)
  • Invalid template name
  • Malformed YAML
Secrets can’t have defaults. Fix in runtm.yaml:
Each template requires a Dockerfile. If missing:
This regenerates the template files.

​
Getting help

If you’re still stuck:
  1. Check logs - Most issues are visible in logs:
  2. Run diagnostics:
  3. Search the docs - Use the search bar above
  4. Open an issue - github.com/runtm-ai/runtm/issues