Troubleshooting

Where failures surface

Every scheduled job logs its runs. Failures show as a red banner on the dashboard Home page, and - if you set up the failure email below - land in your inbox too, at most one email per job per day.

A skipped job is not a failed job: capabilities you haven't finished setting up (no Search Console yet, no DataForSEO) skip quietly by design, and the Home page's setup cards tell you what's missing. The same goes for delays: a machine that was asleep or powered off never emails you - schedules catch up on their own, and only a job that fails while the stack is actually running counts as broken.

Get emailed when something breaks

Optional, two minutes, and strongly recommended if you picked Automatic publish mode: in auto mode nobody opens the dashboard on a normal day, so the email is what actually tells you a job broke. In semi-automatic mode you visit weekly anyway, so the red banner already has you covered - set this up if you'd rather not wait for your next visit.

a. Create a free Resend account. Emails are sent through Resend - free tier, no credit card, and no domain setup needed for this.

b. Create an API key. After signing in, open resend.com/api-keys, click Create API Key, name it dispatchseo, leave the defaults, and copy the key. It starts with re_ and is shown only once.

c. Add two lines to .env. On the machine running DispatchSEO (on a VPS: over SSH, not your own computer), inside the dispatchseo folder, run this with both values replaced - the key you just copied, and your email. The first part checks you're in the right folder before writing anything:

[ -f start.sh ] &&
  echo "RESEND_API_KEY=re_PASTE-YOUR-KEY-HERE" >> .env &&
  echo "ALERT_EMAIL=you@example.com" >> .env &&
  sh start.sh ||
  echo "Wrong folder - run this inside the dispatchseo folder"

One catch to know: ALERT_EMAIL must be the same email you signed up to Resend with. Alerts go out through Resend's built-in sender, which only delivers to its own account's address. (Verified a domain in Resend? Then you can send from it to any address - set ALERT_EMAIL_FROM to something like DispatchSEO <alerts@your-domain.com> in .env too.)

That's it. From the next run onward, failures email you. No email means everything is working.

Docker

Every command in this section runs inside the dispatchseo folder the install created.

Something won't start. docker compose ps shows the state - everything except the one-shot migrate container should be running, and app turns healthy once it can reach the database. docker compose logs app (or logs cron, logs postgrest) has the detail.

Port 4005 is taken. Pick any free port instead:

echo "DISPATCH_PORT=4006" >> .env && sh start.sh

Cron jobs aren't running. docker compose logs cron shows every hit - the schedule prints at startup, and each run logs a timestamped line. Cron failures also ride the dashboard banner + email rails like any other install.

Start over from scratch. This deletes all data, then boots fresh:

docker compose down -v && sh start.sh

The build died with Killed / exit code 137. The machine ran out of memory compiling the app from source - it happens on 1 GB servers when the prebuilt images can't be pulled. Give the machine swap (spillover memory on disk), then start again:

fallocate -l 2G /swapfile && chmod 600 /swapfile && mkswap /swapfile &&
  swapon /swapfile && echo '/swapfile none swap sw 0 0' >> /etc/fstab
sh start.sh

The build gets slower but finishes, and the swap stays useful for the running stack too.

The builder isn't building. docker compose logs builder says exactly what it's waiting for - usually the CLAUDE_CODE_OAUTH_TOKEN in .env, or a project whose setup wizard isn't finished yet.

Search Console

"No GSC data" after connecting. Confirm the service account's email was added as a Full user on the property, and that GSC_SITE_URL matches the property type exactly - sc-domain:example.com for domain properties, https://example.com/ (trailing slash) for URL-prefix ones. First data lands within an hour of a correct setup.

Still stuck

Open a thread in Discussions - include the failing job's log lines if it's a cron issue. Vulnerabilities go through private reporting instead.