Troubleshooting launch errors
Launch error messages, what causes each, and where to read more; covers the retained-context folder errors, the couldn't start line, refusals and broken check environments.
Each row is an error text as the code writes it (<…> stands for a value), what it means, what to do, and the topic to read. The strings are checked against the Go source by a test (internal/kb/kb_errors_test.go).
| error text | what it means | what to do | topic |
|---|---|---|---|
retained context: <path> is a symlink; replace it with a real directory (docs: runs#retained-context) |
.smith or .smith/context under the patch root is a symlink. |
Replace it with a real directory. | retained context |
retained context: <path> is not a directory (docs: runs#retained-context) |
.smith or .smith/context under the patch root is a file. |
Remove it so smith can make the directory. | retained context |
retained context: <path> has permissions <mode>; group/other must have none (chmod 700) (docs: runs#retained-context) |
On Linux or macOS the folder allows group or other access. | Run chmod 700 <path>. |
retained context |
retained context directory: <os error> |
The folder is missing or unreadable. The os error names the path. | Fix the path the os error names. | retained context |
couldn't start <entry>: <error> |
What a failed go writes to the card thread and to app.log (as smith: couldn't start <entry>: <error>). The <error> says why. |
Read the <error>; search app.log for couldn't start. |
logs |
no checks: only the reviewer and the operator check this work; tick run without checks to go |
The project has no checks, so go is refused until you accept that only the reviewer and you check the work. | Add checks, or tick run without checks. | launch |
this card was drafted when <project> had no checks; it has <n> now (<ids>). Draft the card again. (docs: launch#draft-and-go) |
The card was drafted before the project had checks. | Draft the card again. | launch |
desk.json: unknown field "<key>" or harness.json: unknown field "<key>" |
The config loader is strict: a key it does not know, often a renamed one, stops the load. | Fix or remove the key named. | on-disk |
refusing to launch: <kind> <root> is on <fs>, which is lost on reboot. use a directory on persistent disk, or set SMITH_ALLOW_VOLATILE_ROOTS=1 for a throwaway run. |
A root is on tmpfs or ramfs, so its files vanish on reboot. | Use a directory on persistent disk, or set SMITH_ALLOW_VOLATILE_ROOTS=1 for a throwaway run. |
on-disk |
the check environment is broken: <first stderr line> |
A check exited 126 or 127, or printed "command not found". The command is not on the check's PATH. | Name the real executable. On Windows see windows and windows. | windows |
01older builds#
retained context requires private real directories is from builds before the retained-context messages above, and the string is no longer in the code. It fired for a folder that was not a directory, was a symlink, or had group/other permission bits, and named neither the folder nor the reason. Update, or see retained context.