Troubleshooting
What you see, why it happens and what to do, for the problems a DevStride machine or session meets most: sign-ins, Docker, credentials, demo data, machine identities, test runs and the logs to read.
On this page
- Troubleshooting
- ./setup is not found
- Setup stops before asking anything
- Setup refuses to run in a worktree
- ds works only at a checkout's top folder
- AWS does not recognise your work email at setup's sign-in
- Your AWS sign-in has lapsed
- Setup says your AWS profile cannot be used
- Docker is not answering
- Docker has too little memory free for another app
- A golden command stops: Docker ran out of memory
- A credential is missing
- A checkout without its demo data
- ds pool reset refuses other organizations
- AWS refuses the agent machine identity
- Another ds verify run is going
- A stopped setup or ready run left a checkout reserved
- Setup will not edit your shell startup file
- Setup stopped: a new terminal would run another Node
- The stage step is blocked
- Your stage's database is behind your code
- Claude in Chrome is offered but not enabled
- The plugin update fails with installed-payload-mismatch
- The status line shows as modified
- Many tests time out at once
- ds pool or ds work says you do not hold the checkout
- The merge guard refused a command
- When the hourly health check reports a problem
- Where the logs are
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.
./setupis not found- Setup stops before asking anything
- Setup refuses to run in a worktree
dsworks only at a checkout's top folder- AWS does not recognise your work email at setup's sign-in
- Your AWS sign-in has lapsed
- Setup says your AWS profile cannot be used
- Docker is not answering
- Docker has too little memory free for another app
- A golden command stops: Docker ran out of memory
- A credential is missing
- A checkout without its demo data
ds pool resetrefuses other organizations- AWS refuses the agent machine identity
- Another
ds verifyrun is going - A stopped setup or ready run left a checkout reserved
- Setup will not edit your shell startup file
- Setup stopped: a new terminal would run another Node
- The stage step is blocked
- Your stage's database is behind your code
- Claude in Chrome is offered but not enabled
- The plugin update fails with
installed-payload-mismatch - The status line shows as modified
- Many tests time out at once
ds poolords worksays you do not hold the checkout- The merge guard refused a command
- When the hourly health check reports a problem
- Where the logs are
./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/devstrideorgit clonemakes adevstridefolder 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 nosetupfile. 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 tocore.autocrlf=true. This happens on Windows, which the guide does not support, or on a Mac with that setting copied over.
What to do
-
Go into the clone and check
setupis there:cd ~/dev/devstride # or wherever you cloned it ls -l setup # should show -rwxr-xr-x … setup -
If it is missing, bring the clone up to date, then run it:
git switch develop && git pull && ./setupgit switchrefuses while you have uncommitted changes: commit or stash them first. -
A ZIP download: clone it instead, with the one line.
-
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
./setupthere.
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
- Press
sto skip the sign-in for now. Setup finishes everything that does not need AWS and lists what is left; nothing is lost. - Ask an admin to run
ds team add-developerfor you (For admins: Give a developer access). - 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.
- Run
./setupagain. 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
dscommand 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 readyfails a line in itsawsgroup, endingsign in: aws sso login --profile <profile>.ds secrets pullwarns 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
-
Sign in with the profile the message names:
aws sso login --profile <profile>Setup's profile is
devstride-devunless you already had one for the dev account, and setup's block in your shell startup file exports it asDEVSTRIDE_DEV_PROFILE, soaws 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. -
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 configuredat all. The line suggests pointingDEVSTRIDE_DEV_PROFILEat another profile or adding one by hand; on a machine set up with./setup, run./setupagain 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.
./setupnames 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 todevstride-devedits that one line (keeping a copy of the file, ending.before-devstride-setup) and writes thedevstride-devprofile 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./setupagain. - The profile is in
~/.aws/configor~/.aws/credentials: make the change the message names (give the profilesso_session = devstrideand the dev account's id and role, or remove the access-key section), or pointDEVSTRIDE_DEV_PROFILEat a profile that has them. Then run./setupagain.
Docker is not answering#
What you see
- The local app does not load, and
ds pool statusends withDocker is not reachable — containers not surveyed. ds machine readyfails a checkout's database line, endingis Docker running?- Tests and
ds verifycannot reach the test databases.ds verify fullsays the test Postgresis 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
- 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.
- Start the apps again.
ds worktree up mainstartsmain's app. Awt1orwt2app starts when you take that checkout withds pool checkout. - 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./setupagain; 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
- Stop what you are not using: another checkout's app (
ds worktree down <name>, which keeps its data), or another project's containers. - 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./setupasks for. Docker restarts to apply it, which stops every container on the Mac, so pick a moment when nothing is running there. - 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 cognitoand 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, thenCannot find module '/app/.ds/.tmp/golden.mjs'. -
Or
ds pool resetstops 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
-
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. -
Run the command again.
-
After a
ds pool resetthat 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 seedords neonsaysSEED_TOKENorNEON_API_KEYis not in the agent credentials file, and names the file. ds machine readyfails a line in itscredentialsgroup: a checkout's.envis missing keys the bundles deliver, or the agent credentials file lacks a DevStride key. Each line ends with what to run.- In its
awsgroup, thesecretsline 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 saysSEED_TOKENandNEON_API_KEYare 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
-
Pull the latest keys. This needs a working AWS sign-in (see Your AWS sign-in has lapsed):
ds secrets pullIt rewrites every checkout's
.envcompletely, so never edit a.envby hand: the next pull overwrites it. -
Prove it with
ds machine ready(ords machine ready --quick). Eachcredentialsline names whatever is still missing. -
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 statussays a checkout's data isnot recorded (its data could be anything).- At the end of
./setup, under When you can:- a
demo-data record for wt1(orwt2) line beginningnot recorded: its database already exists, so the hourly check leaves its data alone; or - a
demo data in wt1(orwt2) 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.
- a
ds machine readyfails a checkout's demo sign-in, sayingacme.devstride could not sign in.ds fleet statusmarks the checkoutunrecorded.
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
-
Check that the checkout really holds nothing but demo data you can lose. A reset replaces its whole database.
-
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 wt1The 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 resetrefuses other organizations. -
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
./setupagain, 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
-
Find out what the other organizations are, and whether anyone still needs them.
-
If nobody does, reset anyway, in the checkout you hold:
ds pool reset wt1 --discard-other-orgs -
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.
dsstops with the same message instead of opening a sign-in../setup --agent <name>blocks withAWS 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 readyfails itsawslines: the machine'scertificate 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
-
If the machine was revoked on purpose (retired, lost or stolen), stop here: it should stay shut off.
-
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.
-
Check it:
aws sts get-caller-identity --profile devstride-machine-<name>-devThe
Arnit prints (the AWS name of the identity in use) ends inassumed-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:
-
Setup has already made the machine's two certificate requests,
dev.csr.pemandprod.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. -
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./dsruns 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 thedevstride-mgmtprofile unless--mgmt-profile(orDEVSTRIDE_MGMT_PROFILE) names another. The certificate names the machine and account given on the command line, whatever the request says. -
Save the two certificates on the agent machine as
~/.devstride/machine-identity/<name>/dev.signed.pemandprod.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 landords verify fullwaits, 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 landseems 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 readymarks its landing checkheld:another ds verify run is going, thenrun 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 statusshows a checkout held bymachine-setup, with a purpose such asmachine setup demo data pid=<n>ormachine ready pid=<n>.ds pool checkouton it answersBUSY.- 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 readymarks that checkoutheld, saying it wasleft by a stopped ./setup or ds machine ready runand thatthe 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
- Open the file it names and find the lines
# >>> devstride machine setup >>>and# <<< devstride machine setup <<<. - Leave exactly one start line followed by one end line around setup's lines, or delete setup's lines together with both markers.
- Run
./setupagain. 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
- Send the team the line setup printed: it names the Node and pnpm before and after, which is what is needed to fix setup.
- Meanwhile, your terminal is exactly as it was. Everything else setup did stays done, but new terminals miss setup's block:
dsfrom anywhere, Homebrew and mise on your PATH, the machine's name and its AWS profile (DEVSTRIDE_DEV_PROFILE).ds machine readytherefore fails itsshell startup filesline (NOT READY) until it is fixed. Use./dsfrom the top of a checkout until then. - 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'sNEON_API_KEYis 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 pulland./setupagain. -
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
./setupagain. -
A failed first deploy: read
.ds/stage-deploy.login the checkout it deployed from (setup names it). Fix what it shows, or send it to the team, then run./setupagain: it finishes the stage rather than starting over.ds stage create --member wt1 --dry-runshows what is left to do.
Your stage's database is behind your code#
What you see
ds machine readyshows anoteonstage: database, for example3 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 awt1orwt2on newer code can be further ahead than it says../setupplans a steprefresh the stage <stage>: its database is 3 migration(s) behind main's code.ds pool cloudrefuses: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 freewt1orwt2. 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 cloudrefusal): that checkout's code is older than the stage's database. Bring the checkout up to date (pull, or rebase ontodevelop), 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
-
Update the plugin to 3.18.0 or newer (see the entry above), and restart your sessions.
-
Where
git diffshows only that file, and it already matchesdevelop(git diff origin/develop -- .claude/statusline.shprints nothing), put it back:git checkout -- .claude/statusline.sh -
Delete a leftover
.claude/statusline.sh.bakonce 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:
- 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.
- This checkout's test databases have degraded, after a long uptime or a stopped run that left its databases behind.
- 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
-
Rule out the first cause before anything else. Run
docker psand look for another checkout'sdevstride-*-drizzle-testscontainer with a run in progress, and ask the session using it.ds verifyalready runs one deep check per machine; when two runs genuinely must overlap, cap each with--maxWorkers=7. A high load average alone proves nothing. -
Restart this checkout's two test databases.
ds worktree lsnames the pair:docker restart devstride-<slug>-drizzle-tests devstride-<slug>-dynamodb-tests -
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 -
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
tailorgrepreports the pipe's exit code, so a failed run reads as a success. Write the output to a file instead, from thebackendfolder: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 startords work landrefuses, saying the checkout is leased under your session namebut by a different session, that you do not hold it, and that a lease taken from a plain terminal needs theDEVSTRIDE_LEASE_TOKENthatds pool checkoutprinted there.- Or
ds worksaysthis checkout is not leased to you, and names theds pool checkoutcommand 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=…lineds pool checkoutprinted, 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 saysBUSY, 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 fordevelop, and/devstride:releasefor 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 runds tower claimbefore 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 (
mergePathin.claude/ds-config.json), never the guard's switch.
Never switch the guard off to get past a block
DEVSTRIDE_MERGE_GUARD=0turns 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