docs

Troubleshooting

Troubleshooting

Friendly fixes for the errors you're most likely to see.

Troubleshooting

Things sometimes go sideways. Here are the errors you're most likely to bump into and the fixes that get you moving again. If you're seeing something that isn't here, the first step is almost always to check div config get and confirm the CLI is pointed at the host you think it is.

#command not found: div

You installed the package but your shell can't find the binary.

  • Open a new terminal window — npm only updates PATH for new shells.
  • Check npm config get prefix. The bin directory is <prefix>/bin. Make sure that's on your PATH.
  • If you used nvm, fnm, or another Node manager, make sure your shell is using the version where you installed Div (which node should be in the manager's directory).

#Couldn't reach <url>: fetch failed

Network-level failure. The CLI couldn't open a connection to the API host.

Common causes:

  • Wrong URL. Run div config get api-url. If it's not what you expect, run div config set api-url <correct-url> or div config unset api-url to fall back to production.
  • API not running. If pointed at a local Laravel app, make sure it's actually serving (composer run dev or php artisan serve). Confirm with curl -v <url>.
  • DNS issue. If pointed at a .test domain, make sure your local DNS resolver (Herd, Valet, or dnsmasq) is up. dig <domain> should resolve to a local IP.
  • Firewall. Some corporate networks block arbitrary outbound HTTPS. Try from a different network to confirm.

#unable to verify the first certificate / TLS errors

You're hitting a host with a self-signed or untrusted certificate (typically Herd's local cert).

Two fixes, in order of preference:

# Better — point Node at the local CA
NODE_EXTRA_CA_CERTS="$HOME/Library/Application Support/Herd/config/valet/CA/HerdCASelfSigned.pem" \
  div deploy

# Quicker but blunter — disable verification entirely
div config set insecure true

The blunt option only matters for local dev — keep insecure: false (the default) when targeting production.

#Warning: Setting NODE_TLS_REJECT_UNAUTHORIZED to '0'…

Not an error — this is Node telling you that insecure: true is doing its job. Expected when pointing at a .test host. To make it go away, use NODE_EXTRA_CA_CERTS instead (see above).

#SQLSTATE[HY000]: no such column: claim_source

Happens against a local Laravel app whose database is out of date. From the Laravel app's root:

php artisan migrate

#No div.json here

You're not in a Div project folder. Either:

  • cd into one.
  • Or run div new <name> to scaffold a new one.

#No files to deploy from this directory

The folder is empty, or every file is excluded by .divignore / built-in ignores. Add an index.html and try again. See the .divignore page for what's excluded by default.

#This deploy is X MB; cap is 50 MB

The total size of files in your folder exceeds the per-deploy cap. See Limits. Compress images, drop unused assets, or split the project.

#Your session has expired. Re-run div deploy to sign in again.

The CLI has a saved API token on this machine, but the server doesn't recognize it. Two common causes:

  • Local dev. The local Laravel database was reset (migrate:fresh or similar) after the token was issued. The DB row Sanctum looks up no longer matches your saved token.
  • Production. The token was revoked server-side (an admin action, or div logout from another session).

Either way, re-verify:

div deploy   # prompts for email, sends a new verification link

Click the link in your inbox. The fresh token replaces the dead one and subsequent div projects / div whoami / div deploy calls work normally.

div projects auto-clears the stale token after the first 401, so div whoami will correctly say "Not logged in" until you complete a deploy. You don't need to manually delete auth.json (it lives at ~/Library/Preferences/div/auth.json on macOS, ~/.config/div/auth.json on Linux).

#This project has been claimed

You've already verified this project (clicked the link in the email), which clears the per-project claim token the CLI was using. To deploy updates from the CLI, sign in to your account:

div login

After signing in, every div deploy from any folder on this machine works without prompts.

#No saved credentials for <slug> on this machine

Your div.json references a slug, but auth.json doesn't have a claim token for it. Usually:

  • You cloned the project on a new machine.
  • You deleted auth.json at some point.

Same fix as above:

div login

#Saved credentials are no longer valid for this project

The server rotated or cleared the token tied to your slug, but you didn't go through the verification flow. Rare. Sign in to refresh:

div login

#Too many requests

You hit the rate limiter. Wait a minute and try again. Production caps are around 2 deploys per minute per IP.

#Email is required / That does not look like a valid email

You either submitted an empty email at the prompt or one that didn't parse. The CLI does a basic format check (thing@thing.thing); the server enforces the real rules. Most people see this when they hit Enter on an empty prompt by accident.

#The verification email never arrived

  • Check your spam folder.
  • Check the email address you typed — typos happen to the best of us.
  • If you're running locally with MAIL_MAILER=log, check storage/logs/laravel.log. The signed URL is in there.
  • If you're on production and it's still missing after a few minutes, deploy again. The CLI will re-prompt for email and re-send.

#Live reload isn't reloading

div start injects a <script> tag that connects to a WebSocket. If the browser tab isn't reloading on save:

  • Open DevTools → Network → WS. There should be a connection to ws://localhost:<port>/dev-server.
  • If the connection is closed, refresh the page once to re-establish.
  • If you're behind a proxy or VPN that doesn't allow localhost WebSockets, that's the cause. Disable it for localhost.

#EADDRINUSE: address already in use :::3000

Another process is camping on port 3000. div start auto-increments to find a free port — if you're seeing this, something else may be hard-binding. Run with --port:

div start --port 4000

#My website is showing old content

Production CDN cache should revalidate within a request or two of div deploy, since every write sets Cache-Control: no-cache, max-age=0. If you're seeing stale content:

  • Hard-refresh (Cmd+Shift+R / Ctrl+Shift+F5).
  • Check that the deploy actually succeeded — re-run div deploy and look for the ✓ Updated line.
  • Check that you're hitting the right URL (some folks accidentally bookmark a stale slug).

#Still stuck?

If something isn't covered here:

  • Re-run with the relevant subcommand's --help flag to confirm the syntax.
  • Check div config get to confirm where requests are being sent.
  • File an issue with the CLI version (div --version), the command you ran, the full output, and which OS / shell you're on. We're happy to help.