Errors

import { CopyInkError, isCopyInkError } from 'copy-ink'

try {
  await getCopy({ scope: 'about' })
} catch (cause) {
  if (isCopyInkError(cause) && cause.code === 'NOT_SET_UP') {
    // …
  }
}

CopyInkError carries a machine-readable code and a details record alongside its message. Use isCopyInkError rather than instanceof — the library may be present more than once in a dependency tree.

Codes

Code	Raised when
CONFIG_INVALID	The config failed validation, or credentials are missing
NOT_SET_UP	Something read content before setupCopyInk() ran
AMBIGUOUS_CONTENT_FILE	A scope resolves to both x.yml and x/_index.yml
AMBIGUOUS_LOCALE_LAYOUT	Content exists at the root and in a default-locale folder
INVALID_SCOPE	A scope that escapes the content root, or is otherwise unusable
INVALID_FIELD_PATH	A field path that is empty or malformed
MISSING_FIELD	A field has no value and missingField is 'error'
UNKNOWN_LOCALE	A locale not present in locales
UNKNOWN_COLLECTION	A collection name not declared in the config
UNKNOWN_ITEM	An item that does not exist and missingField is 'error'
DUPLICATE_SLUG	Item creation would overwrite an existing slug
INVALID_SLUG	A published slug that is not a-lowercase-slug
INVALID_CHANGE	A publish request carried a change kind copy-ink does not know
UNSAFE_PATH	A write that would land outside the repository
FIELD_LOCKED	An edit targeted a field locked by _locked or editable: false
NOT_AUTHENTICATED	No session, or a sign-in that could not be verified
NOT_AUTHORISED	A valid session whose user is not on the allowlist
STALE_BASE	The branch moved since the editor loaded
BACKEND_ERROR	The forge refused the write
UPLOAD_REJECTED	An upload over maxUploadBytes, or from a disallowed host
YAML_INVALID	A content file could not be parsed

Over HTTP

The route handler maps them onto status codes:

Code	Status
NOT_AUTHENTICATED	401
NOT_AUTHORISED	403
STALE_BASE	409
BACKEND_ERROR	502
any other CopyInkError	400
anything else	500

See the HTTP API.

CLI issues

The CLI does not throw for content problems — it collects Issue values and prints them:

interface Issue {
  severity: 'error' | 'warning'
  code: string
  message: string
  file?: string
  line?: number
  hint?: string
}

Issue codes are listed under check and doctor. A command exits 1 when any issue has severity error.