Troubleshooting
Most cotctl errors are clear and tell you how to fix them. This page collects the ones you're most likely to hit, organized as symptom → cause → fix so you can scan for yours quickly.
Installation & setup
cotctl: command not found after a global install
- Cause: the npm global bin directory isn't on your
PATH. - Fix: confirm where npm installs global binaries with
npm bin -g, and add that directory to yourPATH. As a quick workaround, you can always run the tool vianpx @cotctl/cli <command>.
It was not installed automatically: … / cotctl cannot update itself here: …
- Cause: this copy of
cotctlcan't update itself (from 0.14.0), so it didn't try: there is no write permission on npm's global directory, it is a standalone binary, it was not installed withnpm install -g, or it runs on Windows. The first message comes from the automatic update, the second fromupdateat the prompt orcotctl update. - Fix: run the update command the message prints, with whatever permissions npm's global directory needs —
cotctlnever runssudo. On an update without breaking changes your command still ran, on the current version; from the prompt orcotctl updateit exited1without running anything. See When cotctl can update itself.
Could not update cotctl to <version>: …
- Cause: the update was attempted and npm failed — no network, a registry that didn't answer in time — or
npm root -gpoints somewhere other than where thiscotctllives, as happens when several Node installations (nvm, Volta) each have their ownnpm. - Fix: run the
npm install -gcommand the message prints, with thenpmof the Node installationcotctlruns from. On an update without breaking changes your command still ran, on the current version, andcotctlwill not retry that version for 12 hours; after choosingupdateat the prompt, it stopped without running the command.
Another cotctl process is installing an update right now.
- Cause: a
cotctlin another terminal or script is installing the new version at that moment. Nothing failed. - Fix: on an update without breaking changes your command ran anyway, on the current version. After
updateat the prompt, or fromcotctl update, it exited1without running anything —5when the prompt was offering the fix for a data-loss advisory. Run it again once that install finishes, and do not runnpm install -gmeanwhile: two installs at once can break the global installation.
cotctl <version> has a known data loss in `cotctl <command>` (<id>): …
- Cause: from 0.16.0, a published advisory names this version of
cotctland this command, so the command did not run —--dry-runincluded — and the exit code is5. - Fix: update
cotctlwithcotctl update, or with the command the message prints, and run the command again. To run this version anyway, setCOTCTL_ACCEPT_ADVISORY=<id>with the id the message names;COTCTL_NO_UPDATE_CHECKdoes not turn it off. See Data-loss advisories.
Authentication & profiles
--company/-c is required
- Cause: the command needs to know which company to act on and you didn't say. There's no default profile, by design.
- Fix: add
-c <profile>. Runcotctl profile listto see the available names. - In a pipeline: export an environment credential instead —
COTCTL_TOKENplusCOTCTL_API_URL— and-cbecomes unnecessary. Since 0.12.0 the error also tells you which of the two variables is missing if you exported only one.
Profile '<name>' not found
- Cause: that profile doesn't exist locally (typo, or you never logged in to it).
- Fix: check
cotctl profile list; runcotctl loginif it's missing.
Session expired for profile "<name>" / Failed to refresh token
- Cause: the token is more than 7 days old, or it was revoked server-side.
- Fix: run
cotctl loginagain for that environment.
API Error 401
- Cause: the token is invalid.
- Fix: re-authenticate with
cotctl login. - With
COTCTL_TOKEN: the message names the API URL the token was sent to.cotctlchecks the token's expiry before sending it, so a401here usually means a revoked token, or one issued by another environment thanCOTCTL_API_URL. Mint a fresh ApiToken and update the variable.
… is not recognized as an ApiToken / … is a user session JWT
- Cause: since 0.15.0,
cotctl login --token,--paste-tokenandCOTCTL_TOKENaccept only a token whosetypeclaim isapi-tokenand that carries_idandcompanyclaims. A session JWT copied from the browser has none of that, and neither does an ApiToken old enough to predate the claim. - Fix: mint an ApiToken with
cotctl login, or have an admin issue one from the webclient's ApiTokens panel, and use that one.
API Error 404 on every request, with /api/api/ in the URL
- Cause: before 0.15.0, an
--api-urlorCOTCTL_API_URLending in/apidoubled the prefix. - Fix: update
cotctl. It now drops a trailing/api, with a notice; or remove it from the value yourself.
API Error 403 / Forbidden (HTTP 403)
- Cause: the logged-in user lacks a permission the request needs — for a Survey, usually the survey administration permission. Since 0.14.0,
routines get,routines export,routines test, and an apply of a Routine withoutidthat already exists also needadmin-pbscripts-read— the permissionroutines listalready needed. Which of the two messages you get depends on the kind; see apply. - Fix: this is a Cotalker permissions matter — ask the company's administrator to grant the user the needed permissions, then retry.
Attempted to modify a read-only field (path: …)
- Cause: the server refused a field
cotctlsent in a JobTitle, User or Routine (routines apply) update. - Fix: report it as a bug —
cotctlshould not send that field.
Could not discover API URL from <url>
- Cause: the webclient URL is wrong, or (common on-premise) the webclient doesn't serve the variables file
cotctlreads to find the API. - Fix: double-check the
--url. On-premise, pass the API explicitly with--api-url https://api.empresa.com.
COTCTL_COMPANY_ID=<id> does not match the company of COTCTL_TOKEN
- Cause: the pipeline secret holds a token for another company than the one
COTCTL_COMPANY_IDasserts. - Fix: check which token the secret holds. The run stops before sending anything and exits non-zero; the code depends on the command — see Asserting which company the job expects — so a script should test for non-zero.
Login cancelled — the existing profile "<name>" was not overwritten.
- Cause:
cotctl loginwas about to save a profile under a name that already exists, and the answer toOverwrite? (y/N)was noty. Since 0.16.0 the name can come from-cas well as--profile(see Naming the profile), and the question normally comes before authenticating, so nothing was minted — except when another process created the profile whileloginran, where the message names the token left behind. With no terminal and no--yes, the error readsProfile "<name>" already exists and there is no terminal to confirm the overwrite on.instead. - Fix: pick another name with
-cor--profile, or pass--yesto overwrite — after checking that the name is the profile you mean to replace.
Token does not belong to the specified company
- Cause: the token was issued for a different company than the subdomain/URL you specified.
- Fix: verify the
--subdomainand--urlmatch the environment you intend.
YAML & validation
YAML parse error
- Cause: invalid YAML syntax — usually indentation or a stray character.
- Fix: check indentation (spaces, not tabs) and formatting. Running
cotctl validate -f <file>points at the problem line.
file:// path escapes YAML directory: <path>
- Cause: a
file://reference leaves the YAML file's directory — through.., an absolute path, or a symlink that leads outside it (the message names where). Since 0.14.0 every kind's script fields are read, and the limit is each YAML file's own directory, not the root of--dir. - Fix: copy the file, or the folder, under the YAML file's directory, or write the script inline. See
file://references.
Cannot read file referenced by file://<path> / file:// reference is not a regular file
- Cause: the file a script field names doesn't exist, can't be read, or is a directory. Since 0.14.0 a
CCJSorESMCodestage'sdata.srcis read too — before, it was sent as the literal path, so a reference that never resolved now fails. - Fix: create the file or fix its permissions, point the reference at a file, or write the content inline.
… would be written without data.<key>, which its bot type requires
- Cause: a bot stage lacks an entry the live bot catalog marks required for its type and version — most often a new
PBScriptstage withoutdata.data. Since 0.14.0 every apply refuses it with exit2, its--dry-runtoo. - Fix: give the entry a value. A
PBScriptstage carries its routine's input underdata.data, anddata: {}when the routine takes none. See Requireddataentries.
Identifier conflict on remote validation / Duplicate key error
- Cause: a question
identifieralready exists in another survey in the company — identifiers are unique company-wide, not per survey. - Fix: rename the identifier, prefixing it with the survey code (e.g.
re_nombreinstead ofnombre).
An exec hook doesn't run, or Illegal return statement
- Cause: the script's
srcis missing itsfunction run()wrapper, so a top-levelreturnis invalid. - Fix: wrap the logic in
function run() { ... }(orasync function run()).
filters must be a list
- Cause: a
propertyquestion'sfiltersis written as a map — a single filter missing its leading-. Before0.13.0this passed validation and then broke the apply. - Fix: start each filter with
-. Seeproperty.
jobs must be a list, or "*" for every job title
- Cause: a
personquestion withpersonFilter.allow: jobTitlehasjobsas a single code (jobs: mgr) instead of a list. Before0.13.0this passed validation, and the apply looked up one JobTitle per character of the value. Before 0.16.0 the message readjobs must be a list. - Fix: write it as a list, even for one code:
jobs: [mgr]. For every job title, write the stringjobs: "*". A missingjobsfails withjobs is required when allow is "jobTitle": …. Under any otherallow,jobsis not read. Seeperson.
Identifier "<id>" cannot be reused
- Cause: a question of the company already holds
<id>— or<id>_label, the namecotctlgives<id>'s title question — typically a question some survey stopped declaring, which the server keeps. The remote check refuses it first; under--skip-remote-validationthe server does. Since 0.14.0 this exits2with that hint, instead of1and the server's raw500. - Fix: declare the question with another identifier, e.g. with the survey code as prefix.
max must be at least 1 row — remove it to keep the 50-row cap
- Cause: a
tablequestion'smaxis below 1 — also in a survey exported from a table saved withmax: 0. Refused since 0.14.0. - Fix: remove the
max; the table then takes up to 50 rows. Seetable.
dateMode must be "date" or "date_time"
- Cause: another value on a
datetimequestion or table column —time,datetime, or an emptydateMode:. Refused since 0.14.0; such a value used to be saved as a date only. - Fix:
date_timefor a date and a time of day;date, or nodateMode, for a date only. There is no time-only mode.
Survey with code "<code>" not found
- Cause: no survey in the company — active or inactive — carries that code. On a
survey-type question it means the child survey hasn't been applied yet. - Fix: check the code with
cotctl surveys list --code <code> -c <profile>, which looks up the exact code and includes inactive surveys. For asurveyreference, apply the child first; withapply --dir, put it in a file that sorts before the parent's, or earlier in the same file — surveys are applied in path order, not in reference order.
Unrecognized key at the workflow root: "<key>"
- Cause: a key the workflow root doesn't declare — usually a state-machine field written one level too high, such as
cardLabels. Refused since 0.14.0; it used to be dropped without a word. - Fix: move it under its state machine (
stateMachines[].<key>), or remove it. At the root,codeisnameCodeandnameisnameDisplay.
asset.property must name one Property on a generic asset
- Cause: a state machine's
genericasset has noasset.property, orproperty: []— or (asset.property takes one Property code) it lists more than one. Refused since 0.14.0, before anything is written; the server refuses to save such an asset. - Fix: declare the asset's one Property code as a one-entry list.
cotctl workflows exportwrites it.
…: survey with code "<code>" not found. Apply the survey first.
- Cause: the workflow names a survey the server doesn't have — in a transition's
requiredSurvey, a StartForm'srequiredSurvey.surveyCodeor a state'ssurveyTriggers[].survey. Since 0.14.0 it is refused before the first write (exit1),--dry-runincluded. - Fix: apply the survey first, or add it to the
--dirdirectory, which applies surveys before workflows.
editable is not a schema node field
- Cause: a property type's schema node declares an
editableblock, which the platform drops. Refused since 0.14.0. - Fix: remove it; use
isNonEditable: truefor a field users can't edit.
<Kind> "<identifier>": could not confirm the write: …
- Cause: the server answered a create or an update with a success code but no document, so
cotctlcannot tell whether anything was written. On an update, the target may have been deleted, or belong to another company. Before 0.16.0 the message readthe backend accepted the write but answered with no <kind> document, so nothing was written, whichcotctlcould not know. - Fix: read the entity back (
getorexport) before re-running the apply. The run exits1.
Surveys: orphaned questions
This one is worth understanding because it's easy to avoid and annoying to undo.
- Symptom: after applying a survey with
questions: [], you can no longer re-create questions with the same identifiers. - Cause: applying an empty questions array leaves the old questions behind as orphaned records, and their identifiers (unique per company) now block re-creation.
- Fix / prevention: never apply
questions: []to "clear" a survey. To deactivate a survey, setisActive: falsewithout touching the questions section —cotctlpreserves existing questions automatically when the section is absent. Once it has happened, neithercotctlnor the public API can delete a stored question, which keeps its identifier: declare the question with another identifier, as theIdentifier "<id>" cannot be reusedhint says. Prevention is the play here.
Bots, schedules & routines
These resources arrived in the 0.9–0.11 releases and have a few failure modes worth knowing.
version must be specified / is not a registered version
- Cause: the bot type in your YAML pins a
versionthe backend hasn't registered, or omitsversionfor a type that has no default.cotctlvalidates bot versions at apply time against the live catalog, and an unknown version is an error (exit2) — the message lists the versions that are registered. - Fix: consult the live catalog and pin a real version.
cotctl bot-types versions <BotType>shows every registered version and the default for one type;cotctl bot-types listshows the whole catalog. (An unrecognized bot type — as opposed to version — is only a warning, since the catalog may not list a brand-new backend bot yet.)
looks like a Quartz-style expression / invalid cron
- Cause: a Schedule's
cronfield isn't a valid UNIX cron expression. The most common trap is a Quartz expression (6 or 7 fields) — the webclient's Advanced tab pre-fills Quartz examples, and copying one as-is fails, becausecotctl(and the scheduler) expect 5 fields:minute hour day-of-month month day-of-week. - Fix: drop the seconds and year fields to get a 5-field UNIX expression.
cotctlvalidates the cron client-side at apply time, so you see this before the schedule lands (an invalid cron would otherwise just silently never fire). An unparseable time-zone string fails the same check — verify thetz/timezone value.
bots list doesn't show the bot-type catalog anymore
- Cause: a breaking rename.
cotctl botsnow manages Bot admin entities — the slash-commands (/command) users run in chat — socotctl bots listlists those, not the ParametrizedBot type catalog it used to. - Fix: the type catalog moved to its own command group. Use
cotctl bot-types listandcotctl bot-types versions <BotType>. The oldcotctl bots versions <BotType>still works as a deprecated alias — it prints a warning and delegates tobot-types versions— but it will be removed incotctl1.0.0, so update your scripts now.
A scoped apply exits 2 on a "destructive" change
- Cause: you ran
cotctl surveys applyorcotctl workflows applywith--dry-run --fail-on-destructive, and the dry-run found adangerfinding: a permission list emptied whole, or — since 0.14.0 — questions the survey update would deactivate (reported under--jsonassurvey.questions-deactivated). That's the flag doing its job: exit code2means "a destructive change was detected", distinct from1(runtime error) and0(success). Awarnfinding, such as a deactivation, never changes the code. - Fix: if the change is intentional, apply without the gate — a real apply ignores the flag. If it isn't, you just caught a mistake before it reached the environment — review the diff. An unmodified export made with 0.13.0 or earlier can trip it: re-export first. This gate exists only on the entity-scoped applies, not on the unified
cotctl apply.
Still stuck?
- Re-run the command — many errors include a precise hint about the fix.
- For schema questions, export a working example of the same resource and compare:
cotctl <entity> export <code> -c <profile> -o example.yaml - See the command reference for the exact options and behavior of each command.