Troubleshooting

Common issues and how to fix them.

Deployment Issues

"Could not find wrangler.jsonc or wrangler.toml"

You're not in a jack project directory.

Fix: Navigate to your project root (where wrangler.jsonc lives) and try again.

cd my-project
jack ship

"Authentication required"

Your session expired or was never set up.

Fix: Run the login flow:

# Interactive (opens browser)
jack login
 
# Headless / agent (email verification, no browser)
jack login --email [email protected]
# then: jack login --email [email protected] --code <6-digit-code>
 
# Or set an API token directly
export JACK_API_TOKEN=jkt_abc123...
 
# For BYO mode (your Cloudflare account)
wrangler login

"Cannot open browser in this environment"

You ran jack login in a non-interactive environment (CI, Docker, SSH, agent) without specifying an email.

Fix: Use the headless login flow:

jack login --email [email protected]

Or set JACK_API_TOKEN if you already have a token.

"Worker not found" or "404 after deploy"

The worker exists but isn't responding at the expected URL.

Possible causes:

DNS propagation delay (wait 1-2 minutes)
Route configuration mismatch
Worker crashed on startup

Debug steps:

# Check if worker is deployed
jack projects info
 
# View recent logs (BYO mode only)
jack logs
 
# Redeploy with debug output
jack ship --debug

Build fails with TypeScript errors

Your code has type errors that need fixing before deployment.

Fix: Run the type checker locally first:

npx tsc --noEmit

Fix any errors, then deploy again.

Secrets Issues

"Could not determine project"

You're not in a project directory and didn't specify a project name.

Fix: Either navigate to the project or use the --project flag:

jack secrets list --project my-app

"Failed to set secret"

The project may not be deployed yet, or there's a permission issue.

Debug steps:

# Check project status
jack projects info
 
# Deploy first if needed
jack ship
 
# Then set secrets
jack secrets set API_KEY

VITE_* variables not working at runtime

VITE_* environment variables are embedded at build time, not runtime.

Fix: Add them to your .env file and redeploy:

# .env
VITE_API_URL=https://api.example.com
 
# Redeploy to embed
jack ship

For runtime secrets, use a different name without the VITE_ prefix.

Project Discovery Issues

Projects showing as "cloud only" but files exist locally

jack doesn't know where your local files are.

Fix: Re-scan your projects directory:

jack projects scan ~/dev

"No projects found"

Either you haven't created any projects, or jack doesn't know about them.

Fix:

# Create a new project
jack new my-app
 
# Or discover existing projects
jack projects scan ~/dev

Database Issues

"D1 database not found"

The database hasn't been created yet.

Fix: Add a database to your project:

jack services db

Then redeploy:

jack ship

Database queries failing

Check that your binding name matches what's in wrangler.jsonc.

// wrangler.jsonc has: "binding": "DB"
// Your code should use:
const result = await env.DB.prepare("SELECT * FROM users").all();

Network Issues

"Could not reach jack servers"

Network connectivity issue or the control plane is down.

Debug steps:

Check your internet connection
Try again in a few minutes

Deployment times out

Large builds or slow connections can cause timeouts.

Fix: Run with debug to see what's happening:

jack ship --debug

Still Stuck?

If none of these solutions work:

Run with debug mode:
```
jack ship --debug
```
Check project status:
```
jack projects info
```
Send us feedback:
```
jack feedback
```
Open an issue: github.com/getjack-org/jack/issues