On this page

Troubleshooting#

On this page you find the problem you are looking at, learn why it happens, and fix it. Each entry has the same three parts: what you see, why, and what to do.

Start with ds machine ready. It proves the machine works, one line per proof, and every failing line names its fix. A full run takes a few minutes, because it starts apps and runs a landing check; ds machine ready --quick starts no app and calls no model. A line marked held (another session or check was using what that proof needed), you (a step only you can take) or note never stops the verdict being READY.

./setup is not found#

What you see

zsh: no such file or directory: ./setup (or, in bash, bash: ./setup: No such file or directory). Sometimes instead: bad interpreter: /bin/bash^M: no such file or directory.

Why

./setup means "the file called setup in the folder this terminal is in". It is not found when:

  • the terminal is not inside the clone. A plain gh repo clone devstride/devstride or git clone makes a devstride folder inside the current one, and the terminal stays outside it;
  • the clone is older than ./setup, which arrived in October 2026. A clone on an older branch or commit has no setup file. The one line on Set up your machine never pulls an existing ~/dev/devstride; it stops and says so;
  • the repository was downloaded as a ZIP rather than cloned (setup then fails later instead, saying ds: run this inside a DevStride checkout);
  • (bad interpreter … ^M) git changed the file's line endings to Windows ones, because git is set to core.autocrlf=true. This happens on Windows, which the guide does not support, or on a Mac with that setting copied over.

What to do

  1. Go into the clone and check setup is there:

    cd ~/dev/devstride   # or wherever you cloned it
    ls -l setup          # should show -rwxr-xr-x … setup
    
  2. If it is missing, bring the clone up to date, then run it:

    git switch develop && git pull && ./setup
    

    git switch refuses while you have uncommitted changes: commit or stash them first.

  3. A ZIP download: clone it instead, with the one line.

  4. bad interpreter: git config --global core.autocrlf input, then clone again.

Setup finds its own folder, so once you are in the right clone you can also run it from anywhere as ~/dev/devstride/setup.

Setup stops before asking anything#

What you see

./setup stops in its first minutes, before its first question, with a line starting setup:.

Why

Before anything else, ./setup installs what it needs to run at all: Homebrew, Node and pnpm at the versions mise.toml pins (with mise), and the repository's dependencies. Each line names what failed.

What to do

It says Do this
this is not a DevStride clone Run ./setup from inside the clone (see above).
… is a worktree of … — setup sets up a clone, never a worktree Run it in the clone the message names (see Setup refuses to run in a worktree).
do not run this as root or with sudo Run ./setup as yourself: it asks for your password when it needs it.
mise.toml does not pin node and pnpm — this clone is incomplete Clone again. If it repeats, check git's line endings (bad interpreter above).
installing Homebrew failed … (it needs an administrator account) Your Mac account is not an administrator. Use one that is, or ask whoever manages the Mac to make yours one, then run ./setup again.
Homebrew's installer finished but brew was not found Open a new terminal and run ./setup again.
installing Node and pnpm with mise failed, or mise installed Node 22 and pnpm …, but this run still finds node … , pnpm … Setup puts the Node and pnpm it installs with mise first for its own run, even ahead of a Node that Homebrew installed for another tool. So this message means mise's own install did not land: the message names the Node and pnpm setup found instead. Read what mise printed above it and run mise doctor, then ./setup again.
installing the repository's dependencies failed Read pnpm's message above it (usually the network). Then run ./setup again.
the rest of setup is not checked until those are in place You ran ./setup --dry-run on a new Mac: it cannot look further until those are installed. Run ./setup.

If git itself fails with xcrun: error: invalid active developer path, Apple's command line tools are missing, which often happens after a macOS upgrade: run xcode-select --install, then ./setup again.

Setup refuses to run in a worktree#

What you see

./setup stops at once with a line like:

setup: /Users/jane/dev/devstride/.worktrees/wt1 is a worktree of /Users/jane/dev/devstride — setup sets up a clone, never a worktree, and would otherwise have worked on /Users/jane/dev/devstride. Run it there (cd "/Users/jane/dev/devstride" && ./setup), or clone the repository afresh (git clone git@github.com:devstride/devstride.git ~/dev/devstride) and run ./setup in that clone.

Why

A git worktree (such as wt1 and wt2, or one you made yourself with git worktree add) shares its history with one clone, and setup always works on that clone, not on the folder you ran it in. On a machine with an older clone, running setup from a worktree would quietly set up the old clone instead, whatever state it was in. So setup refuses and names the clone.

What to do

  • Run setup in the clone the message names: cd <that clone> && ./setup.
  • If that clone is not the one you want to work in (an old clone in the middle of a merge, say), clone the repository afresh with the command in the message and run ./setup there.

ds works only at a checkout's top folder#

What you see

ds runs at the top of ~/dev/devstride, but in any folder below it says zsh: no such file or directory: ./ds. At the end of setup, a note says your startup file defines an alias for ds.

Why

The developer guide used to tell everyone to add alias ds='./ds' to ~/.zshrc. An alias wins over setup's ds, which works in every folder of a checkout, so the old alias keeps ds working only at the top.

What to do

Run ./setup again. It removes the exact old alias ds='./ds' line from your startup file itself (usually ~/.zshrc), after keeping a copy of the file, then open a new terminal. Until then, ds machine ready shows a FAIL on "ds from anywhere".

Setup removes only that exact line, written at the start of a line. If your file indents it (inside an if block, say) or defines ds some other way, setup only names it: delete that line yourself, then open a new terminal. Leave setup's own block, between its # >>> devstride machine setup >>> markers, as it is.

AWS does not recognise your work email at setup's sign-in#

What you see

At setup's AWS step the browser opens the DevStride AWS sign-in page (devstride.awsapps.com), and it does not know your work email, or you cannot set a password. Or the sign-in works, but setup still lists "signed in to the dev account" as not done, because your sign-in reaches no dev account.

Why

Your AWS sign-in is created by an admin, with ds team add-developer. Until they run it, there is no AWS user for your email; and a user that has not been added to the developers' group reaches no account. The GitHub step of the setup line stops the same way, with "ask an admin to run ds team add-developer for you", when your GitHub account cannot see the repository yet.

What to do

  1. Press s to skip the sign-in for now. Setup finishes everything that does not need AWS and lists what is left; nothing is lost.
  2. Ask an admin to run ds team add-developer for you (For admins: Give a developer access).
  3. Set your AWS password: sign in at https://devstride.awsapps.com/start with your work email and follow the code or link AWS emails you. If no email arrives, ask the admin: their command printed the one step that sends it.
  4. Run ./setup again. It picks up at the AWS sign-in.

Your AWS sign-in has lapsed#

What you see

  • In a Claude Code or Codex session, the check that runs when a session starts prints one line saying the AWS session for your profile is expired or missing, with the command to run.
  • A ds command that needs AWS opens the sign-in in your browser when you run it at a terminal. From an agent's shell, where nobody can finish a sign-in, it stops instead and prints the command to run, aws sso login --profile <profile>.
  • ds machine ready fails a line in its aws group, ending sign in: aws sso login --profile <profile>.
  • ds secrets pull warns that it could not refresh from AWS, and writes from its local copy instead.

Why

On a person's machine, setup writes a self-renewing AWS sign-in (the sso-session form of an AWS profile). The AWS command line renews it by itself for as long as your AWS IAM Identity Center session lasts. When that session ends, you sign in once more.

Agent machines never sign in: they use certificates instead, and a sign-in can never fix a refused certificate. If the message talks about a machine identity, go to AWS refuses the agent machine identity.

What to do

  1. Sign in with the profile the message names:

    aws sso login --profile <profile>
    

    Setup's profile is devstride-dev unless you already had one for the dev account, and setup's block in your shell startup file exports it as DEVSTRIDE_DEV_PROFILE, so aws sso login --profile "$DEVSTRIDE_DEV_PROFILE" also works. Inside a Claude Code session, type it with a leading ! (! aws sso login --profile <profile>) to run it from the prompt.

  2. Re-run whatever failed. Nothing retries it for you.

Always use the command spelled out in full. Some machines have a shell helper called sso; it exists only where someone pasted it into their shell, and it is never the fix to give anyone.

A lapsed sign-in blocks only what reaches AWS. The local Docker app, ds pool, ds work and ds verify need no sign-in, and ds secrets pull keeps writing from its local copy until you sign in again.

Two cases a sign-in will not fix:

  • The session-start line says the profile is not configured at all. The line suggests pointing DEVSTRIDE_DEV_PROFILE at another profile or adding one by hand; on a machine set up with ./setup, run ./setup again instead: on a person's machine it writes the sign-in session and the dev profile to ~/.aws/config. On an agent machine, run ./setup --agent <name>, which enrols the machine and writes its profiles.
  • Your sign-in lapses about every eight hours. Your profile is the older form that cannot renew itself. ./setup names the change to make in ~/.aws/config (see Setup says your AWS profile cannot be used); the repository's README, "AWS SSO setup", shows both forms.

Setup says your AWS profile cannot be used#

What you see

On its first check of the AWS stage, ./setup (or --dry-run) names your dev profile and what is wrong with it, for example:

  • [profile old-dev] (named by DEVSTRIDE_DEV_PROFILE in your shell) points at account 123456789012, not the dev account …;
  • … reaches account 123456789012, not the dev account …;
  • … signs in on its own and cannot renew itself — replace its sso_start_url and sso_region lines with: sso_session = devstride;
  • … holds access keys, which the AWS CLI uses ahead of any sign-in and which never renew — remove that section, or ….

Why

Setup signs you in to the dev account through one self-renewing DevStride sign-in. A profile left over from earlier work (one that points at another AWS account, an older profile that signs in on its own, or saved access keys) cannot be used for that, and changing it could break whatever else uses it. So setup names the profile, where its name came from, and exactly what to change, and leaves your files alone.

What to do

  • The name comes from your shell (named by DEVSTRIDE_DEV_PROFILE in your shell): at a terminal, setup shows a screen naming the startup file and line, with two choices. 1) Change that line to devstride-dev edits that one line (keeping a copy of the file, ending .before-devstride-setup) and writes the devstride-dev profile on the shared DevStride sign-in; open a new terminal afterwards. Leave the AWS steps for now, which Enter takes, leaves the file as it is: fix the line yourself and run ./setup again.
  • The profile is in ~/.aws/config or ~/.aws/credentials: make the change the message names (give the profile sso_session = devstride and the dev account's id and role, or remove the access-key section), or point DEVSTRIDE_DEV_PROFILE at a profile that has them. Then run ./setup again.

Docker is not answering#

What you see

  • The local app does not load, and ds pool status ends with Docker is not reachable — containers not surveyed.
  • ds machine ready fails a checkout's database line, ending is Docker running?
  • Tests and ds verify cannot reach the test databases. ds verify full says the test Postgres is not accepting connections.
  • Setup waits for Docker Desktop (or OrbStack or Colima, if that is what this Mac uses), or blocks with Docker has <n> CPUs and <x> GB; the backend tests need at least 4 CPUs and 8 GB — raise them in Docker Desktop: Settings, Resources (or the same line naming OrbStack's or Colima's own setting).

Why

Every checkout's app, its database and its test databases run in Docker. On a person's Mac, setup leaves Docker Desktop's own start-up settings as they are, so after a restart Docker may simply not be running. (On an agent machine, setup makes Docker Desktop start whenever someone signs in to the Mac.) The backend tests need at least 4 CPUs and 8 GB of memory given to Docker, which is why setup checks both.

What to do

  1. Open Docker Desktop and wait until it says it is running. If it shows a welcome screen or asks you to sign in, finish or close it: signing in to Docker is not needed.
  2. Start the apps again. ds worktree up main starts main's app. A wt1 or wt2 app starts when you take that checkout with ds pool checkout.
  3. If setup reported too few CPUs or too little memory: in Docker Desktop, open Settings → Resources and give it at least 4 CPUs and 8 GB of memory. In OrbStack, open Settings → System and set the CPU and memory limits, then let OrbStack restart. With Colima, run colima stop && colima start --cpu 4 --memory 8. Run ./setup again; it re-checks Docker's CPUs and memory.

On a Mac with OrbStack or Colima, setup uses that runtime and starts it when it is not running; it never installs Docker Desktop beside it. If OrbStack shows a window when it starts (its welcome screen or a sign-in), finish or close it; signing in is not needed. If Colima does not answer, colima status says why.

Docker has too little memory free for another app#

What you see

./setup, ds worktree up, ds pool checkout or ds machine ready will not start a checkout's app, and says:

not enough Docker memory for another app copy: Docker has 1.8 GB available of 7.7 GB, and another app copy needs about 3.0 GB — stop what you are not using (ds worktree down <name>, or another project's containers) or raise Docker's memory, then try again

In ds machine ready this is a held line, not a failure: the checkout is simply not proven this time. When Docker has less memory than this Mac should give it, a note beside it names the size to set, for example Docker has 7.7 GB of memory; this 64 GB Mac should give it 24 GB for three checkouts and the demo data build — set the memory limit to 24 GB in Docker Desktop: Settings, Resources, then Apply.

Why

Each checkout's app takes about 3 GB of Docker's memory as it starts. Starting one when Docker has less than that free does not just fail that app: Docker runs out of memory and every container on the Mac goes down with it, including other checkouts' apps and test databases. So the start is held until there is room. An app that is already running is never refused, and if Docker's free memory cannot be read, the app starts as before.

What to do

  1. Stop what you are not using: another checkout's app (ds worktree down <name>, which keeps its data), or another project's containers.
  2. Or give Docker more memory: Docker Desktop's Settings → Resources, OrbStack's Settings → System, or Colima's --memory. On a Mac with 32 GB or more, give it half the Mac's memory, up to 24 GB: that is what three checkouts and the demo-data build need together, and what ./setup asks for. Docker restarts to apply it, which stops every container on the Mac, so pick a moment when nothing is running there.
  3. Run the command again.

A golden command stops: Docker ran out of memory#

What you see

  • A golden command (ds worktree cli <checkout> golden build, golden cognito and the others) refuses before it starts:

    not enough Docker memory for a golden command: Docker has 1.2 GB available of 7.7 GB, and a golden command needs about 2.0 GB — stop what you are not using (ds worktree down <name>, or another project's containers) or raise Docker's memory, then try again
    
  • Or one that started anyway dies part-way with The service was stopped, then Cannot find module '/app/.ds/.tmp/golden.mjs'.

  • Or ds pool reset stops at its last step: wt1 was reset to the golden template; only its demo logins failed — rerun: ds pool reset wt1.

Why

Each golden command first packs its script inside the checkout's container, and that alone takes up to about 2 GB of Docker's memory. When Docker has too little free, the packing is killed, and the error names the missing file it would have written rather than the memory. So golden commands now check first and refuse with the line above. The code is not at fault.

What to do

  1. Make room, as in Docker has too little memory free for another app: stop an app copy nobody is using (ds worktree down <name>), or give Docker more memory.

  2. Run the command again.

  3. After a ds pool reset that stopped at its demo logins, the data is already in place (copied and migrated). Run the command its message names again; it takes seconds and also finishes what the pool records about the checkout:

    ds pool reset wt1
    

A credential is missing#

What you see

  • A command refuses for want of a key. For example ds seed or ds neon says SEED_TOKEN or NEON_API_KEY is not in the agent credentials file, and names the file.
  • ds machine ready fails a line in its credentials group: a checkout's .env is missing keys the bundles deliver, or the agent credentials file lacks a DevStride key. Each line ends with what to run.
  • In its aws group, the secrets line says nothing has been pulled yet, or that a bundle has a newer version: run: ds secrets pull.
  • At the end of ./setup, under When you can, a note says SEED_TOKEN and NEON_API_KEY are not on this machine yet.

Why

Keys are never copied by hand. They live in three bundles in the dev AWS account's Secrets Manager: a shared bundle every machine gets, one machine bundle with a single machine's own stage settings, and an agent bundle with the agents' own service keys. ds secrets pull writes the shared and machine bundles into every checkout's .env, and the agent bundle only into ~/.config/devstride/agent.env, never into a .env.

A key is missing for one of two reasons: this machine has not pulled since the key was added, or nobody has stored it yet.

Today's decision (owner, 2026-10-05): the keys are shared, each with full access, to get everything working. Narrower access per person or per machine comes later.

What to do

  1. Pull the latest keys. This needs a working AWS sign-in (see Your AWS sign-in has lapsed):

    ds secrets pull
    

    It rewrites every checkout's .env completely, so never edit a .env by hand: the next pull overwrites it.

  2. Prove it with ds machine ready (or ds machine ready --quick). Each credentials line names whatever is still missing.

  3. If the key is in no bundle yet, the owner creates it with the service, then stores it. The value goes in on stdin, so it never lands in shell history:

    pbpaste | ds secrets set agent <KEY>
    

    Then every machine runs ds secrets pull.

The Seed and Neon keys. SEED_TOKEN (for ds seed deploy, which redeploys a chosen commit) and NEON_API_KEY (for ds neon, which runs the command-line tool of Neon, our Postgres host) are created by an admin, in Seed's and Neon's organisation settings (For admins). Until they exist, those two commands refuse. Your machine's AWS stage also waits on NEON_API_KEY, so setup lists the stage under Needs you until it arrives; nothing else waits on either key. Seed needs no key for ordinary deploys: a merge to develop or master deploys by itself.

Every tool's credential (where it comes from, which bundle holds it, who creates and rotates it, how ds machine ready proves it) is in the repository's credentials map, .claude/skills/ds-credentials/SKILL.md. Credentials and access walks through it.

A checkout without its demo data#

What you see

  • ds pool status says a checkout's data is not recorded (its data could be anything).
  • At the end of ./setup, under When you can:
    • a demo-data record for wt1 (or wt2) line beginning not recorded: its database already exists, so the hourly check leaves its data alone; or
    • a demo data in wt1 (or wt2) line saying why setup left it as it is: another session holds it, it is on a branch, it has uncommitted changes, or it holds organisations besides the demo data.
  • ds machine ready fails a checkout's demo sign-in, saying acme.devstride could not sign in.
  • ds fleet status marks the checkout unrecorded.

Why

Setup builds the demo data once, keeps it as the machine's snapshot, and copies it into each checkout. It only replaces a database it knows is safe to replace: in a checkout nobody is using, holding nothing or only the demo data.

A checkout whose database already existed before setup could record it is not recorded. Its data could be anything, a customer's organisation copied in by hand for example, so nothing resets it on its own: not setup, not the hourly check (ds machine doctor, which keeps idle checkouts current on an agent machine). It waits until a person has looked.

What to do, for wt1 or wt2

  1. Check that the checkout really holds nothing but demo data you can lose. A reset replaces its whole database.

  2. When it is free (nobody holds it, it is not on a branch, it has no uncommitted changes), run the reset that setup printed, under your session's name:

    export DEVSTRIDE_SESSION="<your name>"
    ds pool checkout wt1 --purpose "demo data"
    # in a plain terminal, now run the export DEVSTRIDE_LEASE_TOKEN=… line it printed
    ds pool reset wt1
    ds pool checkin wt1
    

    The reset copies the snapshot in, re-creates the demo logins and records the checkout as holding demo data, so from then on setup and the hourly check keep it current. If the database holds organizations besides the demo data, the reset refuses: see ds pool reset refuses other organizations.

  3. If setup left it because someone was using it, let that work finish and the checkout be handed back. Then run the reset above, or run ./setup again, which fills an empty checkout from the snapshot.

If the reset says there is no golden template yet, the machine has no snapshot. Run ./setup again: it builds one in a free wt1 or wt2, which takes a few minutes.

For main. Setup fills main's database only while it holds nothing else and nobody holds main, and it never moves main's branch or stops its app. When main needs the demo organisation back, rebuild just that organisation in place:

ds worktree cli main golden build     # rebuilds only the Acme demo organisation; other data is untouched
ds worktree cli main golden cognito   # or: only re-create the demo logins

This rebuild is what setup, ds machine ready and the hourly check print for main. A reservation would not do: taking main needs --i-know-main-is-free, and handing it back stops its app.

A demo login left over from an older local setup without an email used to make golden cognito fail. On a checkout's own local sign-in service, such a login is now made again from its database row, and the command's summary counts it (made again (local logins with no email)). Real AWS sign-ins are never touched this way.

ds pool reset refuses other organizations#

What you see

wt1's database holds 2 organization(s) besides the demo data (…), and a reset replaces all of it — if they are not needed: ds pool reset wt1 --discard-other-orgs

Or cannot read which organizations wt1's database holds, so it is not reset unread, with the same command.

Why

A reset replaces the checkout's whole database with the demo-data snapshot. A customer's organization copied in by hand (ds worktree cli <checkout> data copy) leaves no record in the pool, so the reset looks at the database itself and will not delete what it did not put there. A checkout in client mode (--mode client) is different: its reset snaps back to its own customer copy, and this check does not apply.

What to do

  1. Find out what the other organizations are, and whether anyone still needs them.

  2. If nobody does, reset anyway, in the checkout you hold:

    ds pool reset wt1 --discard-other-orgs
    
  3. If someone does, leave the checkout as it is and work in the other one. Next time, copy a customer in with client mode (ds pool checkout <checkout> --mode client --org <id>), which the pool records, so a reset snaps back to that copy instead.

AWS refuses the agent machine identity#

What you see

  • The check at session start says the AWS machine identity for the profile was refused, and that a login will not fix it, because it is certificate-based.
  • ds stops with the same message instead of opening a sign-in.
  • ./setup --agent <name> blocks with AWS refused <name>'s identity (revoked, expired, or its key is gone) — setup never replaces an identity by itself; re-enrol on purpose: ds machine enroll <name> --force, then run setup again (runbook: .claude/skills/ds-machine-identity).
  • ds machine ready fails its aws lines: the machine's certificate identity was refused or has expired.

Why

An agent machine (one that runs sessions with nobody at the keyboard) cannot sign in through a browser, so it has its own certificates: one for the dev AWS account and one for production. AWS exchanges them for short sessions named after the machine. They last a year.

AWS refuses them when the machine was revoked (ds machine revoke), when the certificate has expired, or when the machine's key file is gone. No sign-in can fix that, so nothing offers one.

What to do

  1. If the machine was revoked on purpose (retired, lost or stolen), stop here: it should stay shut off.

  2. Otherwise give it a new identity. This is also the yearly renewal:

    ds machine enroll <name> --force
    ./setup --agent <name>
    

    The first command makes new keys, and removes the old certificates and the machine's two AWS profiles. Setup then asks for one AWS approval in the browser, signs and installs the new certificates, and checks that both accounts answer as this machine. The machine has no AWS access from the first command until setup finishes, so do it while no session needs AWS.

  3. Check it:

    aws sts get-caller-identity --profile devstride-machine-<name>-dev
    

    The Arn it prints (the AWS name of the identity in use) ends in assumed-role/devstride-machine-identity/<name>.

When the approver cannot sign: the administrator route. The one approval must come from someone whose AWS sign-in can sign with the management account (where the certificate authority lives). If yours cannot, setup says so, and names this route instead:

  1. Setup has already made the machine's two certificate requests, dev.csr.pem and prod.csr.pem, in ~/.devstride/machine-identity/<name>/ on the agent machine. They hold no secrets: copy them to the administrator. The machine's private keys (dev.key, prod.key) never leave it.

  2. The administrator, in their own DevStride checkout and signed in to the management account, signs both:

    ds machine sign <name> --account dev --csr <full path to dev.csr.pem> --out dev.signed.pem
    ds machine sign <name> --account prod --csr <full path to prod.csr.pem> --out prod.signed.pem
    

    ./ds runs from the top of the checkout, so give the requests' full paths; the certificates are written to the top of that checkout. It signs with the devstride-mgmt profile unless --mgmt-profile (or DEVSTRIDE_MGMT_PROFILE) names another. The certificate names the machine and account given on the command line, whatever the request says.

  3. Save the two certificates on the agent machine as ~/.devstride/machine-identity/<name>/dev.signed.pem and prod.signed.pem, then run ./setup --agent <name> again. It installs them with no sign-in.

The repository's ds-machine-identity skill is the full runbook, including how to revoke a machine.

Another ds verify run is going#

What you see

  • ds verify land or ds verify full waits, and about once a minute prints a line ending — one deep check per machine at a time, naming the folder, process and start time of the run it is waiting on.
  • ds work land seems to hang at its local check, which is that same command. Its waiting line goes to .ds/work-land.log, not to the screen.
  • ds machine ready marks its landing check held: another ds verify run is going, then run ds machine ready again once it has finished.

Why

A machine runs one deep check at a time. Two full test runs on one machine starve each other of CPU, and the timeouts that follow look exactly like broken code. So every ds verify run takes a machine-wide lock, ~/.cache/devstride/verify.lock, and the next one waits its turn.

What to do

Wait: your run starts as soon as the other finishes. The waiting line tells you whose run it is. There is nothing to clear by hand: a run that died leaves its lock behind, and the next run reclaims it by itself and says so. For ds machine ready, run it again once the other run has finished.

A stopped setup or ready run left a checkout reserved#

What you see

  • ds pool status shows a checkout held by machine-setup, with a purpose such as machine setup demo data pid=<n> or machine ready pid=<n>. ds pool checkout on it answers BUSY.
  • When it was stopped, setup printed Stopped while setup held <checkout>: its lease stays, because a copy may still be finishing inside Docker.
  • ds machine ready marks that checkout held, saying it was left by a stopped ./setup or ds machine ready run and that the next full ds machine ready or ./setup takes it back.

Why

Setup and ds machine ready reserve a checkout while they copy demo data into it or start its app. If they are stopped part-way (Ctrl-C, a closed terminal), they deliberately keep the reservation: a copy may still be finishing inside Docker, and handing the checkout over then would give someone a database that is still being rewritten.

What to do

Nothing by hand. Once the stopped process has gone, the next full run takes the reservation back and stops any app it left running: ./setup, a full ds machine ready (not --quick), or on an agent machine the hourly check. It says took back the reservation a stopped setup run left on <checkout>. Never delete the reservation yourself.

The hourly check (ds machine doctor) keeps its own reservation the same way when it is stopped part-way. It prints the exact command that frees the checkout sooner, once nothing is running there, and its next scheduled run takes the checkout back anyway.

Setup will not edit your shell startup file#

What you see

./setup lists a shell startup files line under Needs you:

setup will not edit <file> (it has a "# >>> devstride machine setup >>>" or "# <<< devstride machine setup <<<" line without its pair, or more than one block) — leave one pair of its marker lines, or none, then run setup again

Why

Setup keeps its lines (ds on your PATH, Homebrew, mise and the pinned Node, this machine's name and AWS profile) in one block between two marker lines in your shell's startup file, and rewrites only what is between them. When a marker is missing, or there are two blocks, it cannot tell where its block ends: pairing a stray start line with a later end line would delete your own lines in between. So it changes nothing and asks you.

The file depends on your shell: for zsh, ~/.zshrc, plus small blocks in ~/.zshenv, which every zsh reads, scripts included, and ~/.zlogin; for bash on a Mac, ~/.bash_profile (or ~/.bash_login or ~/.profile, whichever bash reads); for bash on Linux, ~/.bashrc. The message names the file.

What to do

  1. Open the file it names and find the lines # >>> devstride machine setup >>> and # <<< devstride machine setup <<<.
  2. Leave exactly one start line followed by one end line around setup's lines, or delete setup's lines together with both markers.
  3. Run ./setup again. It rewrites everything between the pair, or adds a fresh block when there is none.

Before its first change to a startup file, setup keeps a copy of it beside the original with .before-devstride-setup added, for example ~/.zshrc.before-devstride-setup. Compare against it to tell your own lines from setup's. Keep your own lines outside the block: setup rewrites the block on every run.

Setup stopped: a new terminal would run another Node#

What you see

./setup lists a shell startup files line like this:

setup's shell blocks would make a new terminal run another node (node: v22.11.0 → v24.3.0); they were taken back out and your startup files are as they were — this is a setup defect: tell the team, with this line

Why

After writing its block into your shell's startup files, setup opens a fresh login shell and checks which Node and pnpm it finds. A new terminal may keep the Node and pnpm it ran before, or move to the Node 22 and pnpm setup itself installed (see Which Node your terminal runs afterwards). Anything else would be a surprise that could break other projects, so setup takes its block back out at once, and nothing about your terminal has changed.

A related line, a new terminal did not answer after setup's shell blocks were written, means the check itself could not finish: the new shell took longer than a minute or stopped. Setup took its blocks back out in the same way. Open a new terminal to see what it does on start-up, fix that, then run ./setup again.

What to do

  1. Send the team the line setup printed: it names the Node and pnpm before and after, which is what is needed to fix setup.
  2. Meanwhile, your terminal is exactly as it was. Everything else setup did stays done, but new terminals miss setup's block: ds from anywhere, Homebrew and mise on your PATH, the machine's name and its AWS profile (DEVSTRIDE_DEV_PROFILE). ds machine ready therefore fails its shell startup files line (NOT READY) until it is fixed. Use ./ds from the top of a checkout until then.
  3. If you want to compare by hand, setup kept a copy of every startup file it touched, ending .before-devstride-setup (for example ~/.zshrc.before-devstride-setup).

The stage step is blocked#

What you see

./setup lists the stage under Needs you, with one of these:

  • this machine has no Neon key: the team's NEON_API_KEY is not on this machine;
  • holds a database but names no stage: a stage made by hand: this machine had a stage before setup made them;
  • could not look at this machine's stage: the AWS sign-in lapsed or the look failed;
  • a failed first deploy, with the deploy's last lines.

Or ds machine ready fails a stage: line with one of its own: could not be looked at (…) — is the AWS sign-in valid?, this machine has no stage yet — run: ./setup, or its first deploy has not finished — run: ./setup. Run ./setup to see which of the cases above it is. (A missing Neon key shows in ds machine ready only as a note under credentials.)

Why

Your stage's database is its own Neon branch, made with the team's Neon key, and its first deploy runs from a pool checkout. Setup builds the stage only when everything it needs is in place, and never rebuilds a stage that already exists.

What to do

  • No Neon key: an admin adds it once for the whole team (For admins). Then run ds secrets pull and ./setup again.

  • A stage made by hand: adopt it once, never rebuilt. From inside ~/dev/devstride, take wt1 (it must have no uncommitted changes), name the stage, and hand wt1 back:

    export DEVSTRIDE_SESSION="<your name>"
    ds pool checkout wt1 --purpose "adopt my stage"
    # in a plain terminal, now run the export DEVSTRIDE_LEASE_TOKEN=… line it printed
    ds stage create --stage <its name> --member wt1
    ds pool checkin wt1
    
  • AWS sign-in lapsed: see Your AWS sign-in has lapsed, then run ./setup again.

  • A failed first deploy: read .ds/stage-deploy.log in the checkout it deployed from (setup names it). Fix what it shows, or send it to the team, then run ./setup again: it finishes the stage rather than starting over. ds stage create --member wt1 --dry-run shows what is left to do.

Your stage's database is behind your code#

What you see

  • ds machine ready shows a note on stage: database, for example 3 migration(s) behind main's code — ./setup refreshes it, or by hand holding wt1 or wt2: ds stage create --member <wt1|wt2> --refresh. It compares with the main checkout only, so a wt1 or wt2 on newer code can be further ahead than it says.
  • ./setup plans a step refresh the stage <stage>: its database is 3 migration(s) behind main's code.
  • ds pool cloud refuses: the stage <stage>'s database has … that wt1's code lacks, and nothing downgrades a database.

Why

Your checkouts' code moves forward with develop; the stage stays where it was until something brings it current. The hourly check never looks at the stage's database, because that would wake it every hour.

What to do

  • Behind: run ./setup, which refreshes the stage in a free wt1 or wt2. Or do it yourself, holding one of them: ds stage create --member wt2 --refresh (see Bringing the stage current). Also, ds pool cloud <checkout> now applies that checkout's missing migrations to the stage before it binds, so binding a checkout is enough when only the database is behind.
  • Ahead of a checkout (the ds pool cloud refusal): that checkout's code is older than the stage's database. Bring the checkout up to date (pull, or rebase onto develop), then bind again. Nothing was stopped or started.

Claude in Chrome is offered but not enabled#

What you see

Setup's When you can list says Claude in Chrome is offered but not enabled yet, or Claude in Chrome: setup could not write Chrome's extension list (…).

Why

Setup asks Chrome to offer the Claude extension, but only you can turn an extension on and sign in to it. Agents do their browser work through it, so until it is enabled they hand browser steps back to you.

To make the offer, setup writes a small file into Chrome's folder. Some Macs do not allow that: a device-management or security policy, a locked folder (ls -lO shows uchg on it), or a terminal without Full Disk Access. Setup then carries on without it and says so; the rest of the run is unaffected.

What to do

Open Chrome. It shows a notice that a new extension, Claude, was added: click Enable. Then open the extension and sign in to Claude. If you dismissed the notice, open chrome://extensions and switch Claude on there. On an agent machine, do this in its DevStride Agent Chrome profile.

If setup could not write Chrome's extension list, there is no notice. Either fix the cause the note names and run ./setup again, or install Claude in Chrome yourself from the Chrome Web Store link in the note, then enable it and sign in to Claude in it.

The plugin update fails with installed-payload-mismatch#

What you see

/devstride:update, or the plugin's update at session start, refuses with installed-payload-mismatch. Deleting the folder it names does not help: the next attempt fails the same way.

Why

Plugin 3.17.0's status line loaded one of the plugin's own Python files on every refresh, and Python saved a compiled copy of it inside the installed plugin. The update checks the installed files against the published release, counted that copy as a file that does not belong, and refused. The status line wrote it again within seconds, so deleting it never stuck. Plugin 3.18.0 fixes both sides, and the DevStride repository now requires it.

What to do

Update once with Claude Code's own commands, from the main checkout (~/dev/devstride), then restart every Claude Code session:

claude plugin marketplace update devstride
claude plugin update devstride@devstride --scope project

Or run ./setup, which clears that copy before it updates and brings Codex's copy of the plugin level too. From 3.18.0 on, /devstride:update works again.

The status line shows as modified#

What you see

git status in main, wt1 or wt2 shows .claude/statusline.sh as modified (sometimes with an untracked .claude/statusline.sh.bak beside it) although you never touched it. Commands that need a clean checkout then refuse it: ds pool checkout will not move it to the latest develop.

Why

Before plugin 3.18.0, the plugin's session-start check rewrote the repository's status line in every checkout whenever the plugin carried a newer copy, even where the branch was about to receive that same copy. From 3.18.0 it leaves the file alone on develop, master, a release branch and a detached checkout, and where the branch's upstream already has the newer copy it prints one line instead: status line v<x> is already on <ref>; pull to get it. On a feature branch it still refreshes the file and asks you to commit it. Its backup now goes in the repository's git folder, not beside the file.

What to do

  1. Update the plugin to 3.18.0 or newer (see the entry above), and restart your sessions.

  2. Where git diff shows only that file, and it already matches develop (git diff origin/develop -- .claude/statusline.sh prints nothing), put it back:

    git checkout -- .claude/statusline.sh
    
  3. Delete a leftover .claude/statusline.sh.bak once you no longer need it.

./setup's move of the main checkout to the latest develop already treats a file that matches develop as no change of yours, so it is not stopped by this.

Many tests time out at once#

What you see

Dozens of test files fail with Test timed out or Hook timed out, or a run takes several times longer than usual. Two signs that the code is not to blame: a different set of files fails on each run, and the failing tests were skipped with no assertions after a setup step timed out, rather than failing an assertion.

Why

Three causes look exactly like broken code:

  1. Another checkout on this machine is running a test suite at the same time. Each checkout has its own test databases, so the two runs cannot corrupt each other, but they starve each other of CPU.
  2. This checkout's test databases have degraded, after a long uptime or a stopped run that left its databases behind.
  3. The test databases restarted seconds ago and Postgres is not accepting connections yet. The failures then cluster at the very start of the run, all in the setup step.

What to do

  1. Rule out the first cause before anything else. Run docker ps and look for another checkout's devstride-*-drizzle-tests container with a run in progress, and ask the session using it. ds verify already runs one deep check per machine; when two runs genuinely must overlap, cap each with --maxWorkers=7. A high load average alone proves nothing.

  2. Restart this checkout's two test databases. ds worktree ls names the pair:

    docker restart devstride-<slug>-drizzle-tests devstride-<slug>-dynamodb-tests
    
  3. Wait until Postgres answers. Use a readiness check, never a fixed pause:

    until docker exec devstride-<slug>-drizzle-tests pg_isready -U postgres; do sleep 1; done
    
  4. Run again. If it still fails, run the same files on a commit you know was good. Failing the same way there means the environment; passing there means your change.

Two traps hide the real result:

  • Piping a test run through tail or grep reports the pipe's exit code, so a failed run reads as a success. Write the output to a file instead, from the backend folder: pnpm test:suite:ci:non-golden > run.log 2>&1; echo "GATE_EXIT_CODE=$?".
  • After Docker or the Mac crashes, the test Postgres may be damaged: for speed it runs without crash-safety flushes. If the suite cannot connect, or reports missing files, remove this checkout's test Postgres with docker rm -f devstride-<slug>-drizzle-tests; the next run recreates it.

ds verify land already re-runs, once, up to five files that timed out during setup when no test failed. The full procedure, with measured examples, is in the repository's testing guide: Diagnosing a mass test failure. Running Tests Per Instance explains the per-checkout test databases.

ds pool or ds work says you do not hold the checkout#

What you see

  • ds pool reset, ds pool checkin, ds work start or ds work land refuses, saying the checkout is leased under your session name but by a different session, that you do not hold it, and that a lease taken from a plain terminal needs the DEVSTRIDE_LEASE_TOKEN that ds pool checkout printed there.
  • Or ds work says this checkout is not leased to you, and names the ds pool checkout command to run.

Why

A lease records which session took it, not just the name: two sessions can share one name. A Claude Code or Codex session proves it is the holder with its own session id. A plain terminal has no such id, so ds pool checkout handed it a one-time token instead.

What to do

  • In the plain terminal that took the lease, run the export DEVSTRIDE_LEASE_TOKEN=… line ds pool checkout printed, then try again. Run later commands in that same terminal.
  • If you never took the lease, take it: ds pool checkout <checkout> --purpose <item>. If that says BUSY, another session holds it: ask that session, or take another checkout.
  • A lease taken before leases recorded their holder is refused by these commands. Hand it back by hand only if you are sure it is yours; otherwise it is the owner's to clear.

The merge guard refused a command#

What you see

A git push, git merge, gh pr merge or gh api command is refused before it runs, with a one-sentence reason from the merge guard.

Why

Every Claude Code and Codex session runs the merge guard before each shell command. It refuses the commands that would skip review: a push to develop or master, a forced or deleting push to a release branch, a merge into develop from a branch the merge-path rule does not admit, a merge into master from anything but a release or hotfix branch, writes to GitHub's branch rules, and any release step (a push to a release branch, a release pull request into master, a release merge) from a session that does not hold the release clearance. Develop has the full list.

What to do

  • Take the normal route: ds work land (or /devstride:build-item) for a Story or one-off, a pull request for anything bound for develop, and /devstride:release for production.

  • "without release clearance": run ds tower status. If another release holds it, wait; your work ships with the next release. If none does, start the release with /devstride:release, which claims it, or run ds tower claim before a release step you do by hand. Release: one release at a time explains the rule.

  • If you think the refusal is wrong, ask the rule for its verdict and reason:

    ds merge-path check --head <branch> --base develop --labels <label1,label2>
    

    If the rule itself is wrong, the fix is the rule (mergePath in .claude/ds-config.json), never the guard's switch.

Never switch the guard off to get past a block

DEVSTRIDE_MERGE_GUARD=0 turns the guard off. It is never the way past a refusal: the block is the point. Ask the owner.

When the hourly health check reports a problem#

The health check (ds machine doctor, run hourly on an agent machine and inside every ds pool checkout) fixes what it may and reports the rest. What its messages mean:

It says Do this
on <branch>, … — only reported A session is working on a branch there. Let it finish and hand the checkout back
… with uncommitted changes — needs a person or … local commits on no branch — needs a person The checkout has changes or commits that would be lost. Commit them to a branch, stash them or discard them
… this code lacks — needs a person The checkout's database is ahead of its code: it was moved back to older code. Move it forward to develop, or, if it holds only demo data, reset it: ds pool checkout <checkout> --purpose "demo data", then ds pool reset <checkout> and ds pool checkin <checkout>, each with your session's name
newer … available — run: ds secrets pull Run ./ds secrets pull when no session is relying on the current .env.
every .env still holds the agent's credentials … — run: ds secrets pull This machine last pulled before agent credentials moved out of .env. One ./ds secrets pull removes them and writes ~/.config/devstride/agent.env
customer data for org … past the 14-day review A customer copy is older than 14 days. Once the repro is done, drop it from the session that holds the checkout: ds pool release-client <checkout> (with that session's name, and its DEVSTRIDE_LEASE_TOKEN in a plain terminal). The unattended run does it for you on a checkout nobody holds
… holds <n> organization(s) besides the demo data, so it is never reset automatically Someone copied other organizations in by hand. Reset it only once nobody needs them, with the command the line gives (ds pool reset <checkout> --discard-other-orgs); see ds pool reset refuses other organizations
Codex has devstride <x>, Claude Code <y> — run: … Codex's copy of the plugin is behind Claude Code's and was not updated (a pin, automatic updates turned off, or --check-only). Run the command it names, or ./setup. When it updates the copy itself, restart running Codex sessions
no pool record says this is golden data Reset it by hand only if that checkout really holds only demo data: ds pool checkout <checkout> --purpose "demo data", then ds pool reset <checkout> and ds pool checkin <checkout>, each with your session's name
… — run: ds machine setup Run ./setup from the main checkout (with --agent <name> on an agent machine)
held by … — only reported Someone holds it. Nothing to do

Where the logs are#

Paths starting with .ds/ are inside a checkout. Setup's and ds machine ready's logs are always in the main checkout: the clone itself, ~/dev/devstride if you used the one line.

Log What writes it
.ds/machine-setup.log (main checkout) ./setup: every line it printed. A --dry-run writes none
.ds/machine-setup-data.log (main checkout) The demo-data build and copies during setup
.ds/stage-deploy.log Your AWS stage's first deploy, in the checkout it deployed from
.ds/machine-ready.log (main checkout) A full ds machine ready: the apps it started, the landing check, the Codex checks
.ds/verify-land.log ds verify land, in the checkout it ran in, every step's whole output. The receipt is .ds/verify-land.json
.ds/verify-full.log ds verify full, in the same way. The receipt is .ds/verify-full.json
.ds/work-land.log The local check that ds work land ran
.ds/sst-types.log Why generating the SST types failed (cli/ensure_sst_types.sh)
~/.devstride/logs/machine-doctor.log The hourly check, ds machine doctor
~/.cache/devstride/merge-guard.log The merge guard, when it could not run and let a command through

When you ask for help with a failed setup step, send the line setup printed for that step, .ds/machine-setup.log, and for the demo data .ds/machine-setup-data.log.

Next: back to the Overview

Powered by DevStride