Errors and limits

This page explains the errors you can see from the SDK and the areca command, and the limits that apply to the site API. Use it when a command fails or a request is refused.

The CLI prints each error message to stderr and exits with code 1. The SDK throws an Error with the same message. Messages are shown exactly as the code produces them. Values in angle brackets, such as <key>, are replaced with your values.

Identifier rulesCopy Anchor Link

Collection keys, site content keys and field keys are identifiers. The SDK checks them before it sends anything to the CMS or writes any file. An identifier must:

• Start with an ASCII letter.
• Contain only ASCII letters, digits, _ and -.
• Be 64 characters or fewer.
• Not be a reserved name. Reserved names are matched without regard to case, so MANIFEST and Con are rejected too.

A field's collection and after values follow the same rules.

Reserved names for every key and fieldCopy Anchor Link

No collection, site content section or field may use these names:

__proto__, prototype, constructor, manifest, con, prn, aux, nul, com1, com2, com3, com4, com5, com6, com7, com8, com9, lpt1, lpt2, lpt3, lpt4, lpt5, lpt6, lpt7, lpt8, lpt9

manifest is the name of the pulled manifest file. __proto__, prototype and constructor would clash with JavaScript object properties. The com and lpt names are Windows device names.

Reserved names for collections and site contentCopy Anchor Link

A collection key or a site content key may not be one of these names. The SDK compares the camelCase form of the key, so preview-globals and preview_globals count as previewGlobals:

resolve, href, preview, globals, previewGlobals, previewFrom, in, languages, matchLocale

These are the members of the generated content object. Field keys may use them: a field called href or preview is fine.

Errors for identifiersCopy Anchor Link

These messages come from areca manifest push, areca manifest pull, and areca pull. The SDK checks the names before any file is written.

Typed content errorsCopy Anchor Link

areca pull and pullContent also check names and values in camelCase. These checks run before anything is written. See typed content for the rules.

A warning, not an error, appears when the publication has no embedded schema: Publication <id> has no embedded schema; types use the current CMS schema. Go live again to embed it. The pull still succeeds.

Output path errorsCopy Anchor Link

areca pull, pullContent and readContent check that each collection file stays inside the output folder and is not a symbolic link.

A failed areca pull can leave the folder partly updated. See areca pull.

Configuration errorsCopy Anchor Link

These errors appear when a required setting is missing.

Environment variables are read from .env.local and .env, and from the shell. See CLI reference for the precedence rules.

Setup errorsCopy Anchor Link

These errors come from areca init.

When you cancel the interactive init prompts, the command prints Operation cancelled. and exits with 0.

Publication and site key errorsCopy Anchor Link

No publicationCopy Anchor Link

No publication exists for this site. Publish content in the CMS before running areca pull.

This appears when the site has never gone live, or the CMS returns a 404 for the snapshot. The CMS's own message, No publication exists, is added after it when present. Publish the site in the CMS, then run areca pull again.

Missing site keyCopy Anchor Link

No siteKey found. <path> does not exist and ARECA_SITE_KEY is not set. Run areca init first.

This comes from areca manifest pull when the config file is missing, or has no siteKey, and ARECA_SITE_KEY is not set. Run areca init, or set ARECA_SITE_KEY.

Manifest overwriteCopy Anchor Link

Remove collection legacy in ./areca.config.ts. Re-run with --yes to confirm.
<path> already defines 2 collection(s). Re-run with --yes to overwrite it.

areca manifest pull stops when it cannot ask you and the pull would remove a collection, a site content section, a field, a language, or the main language. The first message names the removal. It also stops before replacing a populated config that it did not write; the second message is for that case. Re-run with --yes, or run the command in a terminal and confirm the prompt.

Failed to reach CMSCopy Anchor Link

Failed to reach CMS at https://cms.example.com. fetch failed. If the CMS is up, publish content before running areca pull.

The request never got an HTTP response. The message includes the CMS URL and the network error. Check the following:

• The ARECA_CMS_URL value, including the protocol and port.
• That the CMS is running and reachable from this machine.
• Any proxy or VPN in the way.

The last sentence is the same for every command, so it can be misleading. A failed areca manifest push has nothing to do with publishing.

HTTP errorsCopy Anchor Link

When the CMS responds with an error status, the SDK throws a message in this form:

<action> (<status>): <CMS error message>

If the CMS response has no JSON error message, the message ends after the status, for example Failed to fetch snapshot (500).

The actions are Failed to sync manifest, Failed to fetch manifest, Failed to fetch snapshot and Failed to fetch preview.

Rate limits and 429 responsesCopy Anchor Link

When you exceed the site API limit, the CMS returns 429. It also sends a Retry-After header with the number of seconds until the window resets. The SDK formats the message, for example Failed to fetch manifest (429): Too many requests.

The SDK does not retry, and it does not read Retry-After. Its errors contain only the message text. If your build needs to retry, catch the error in your code and wait before you call again. To use the exact Retry-After value, call the HTTP API directly.

import type { ArecaClient } from '@areca-cms/site-sdk'

// The SDK does not retry. This helper retries a 429 after a fixed 60 seconds,
// which matches the length of the rate-limit window.
async function fetchSnapshotWithRetry(client: ArecaClient, attempts = 3) {
  for (let attempt = 1; ; attempt += 1) {
    try {
      return await client.fetchSnapshot()
    } catch (error) {
      const rateLimited = error instanceof Error && error.message.includes('(429)')
      if (!rateLimited || attempt >= attempts) throw error
      await new Promise((resolve) => setTimeout(resolve, 60_000))
    }
  }
}

API error bodyCopy Anchor Link

The CMS returns errors as JSON with an error string:

{ "error": "Unauthorized" }

Some 400 responses also have an issues value that lists the problems in the request:

{
  "error": "Invalid body",
  "issues": [
    { "code": "invalid_type", "path": ["collections", "articles", "fields", 0, "label"], "message": "Invalid input" }
  ]
}

The SDK reads only the error string. It does not show issues. To see them, call the HTTP API directly. The text of each issue depends on the problem.

Responses that are not JSON have no message, so the SDK shows only the status.

Site API limitsCopy Anchor Link

These limits apply to the site API that your build calls.

When a limit is reached, the response is 429 with Retry-After. See Rate limits for every limit in the CMS, and for how the limits are counted.

Payload limitsCopy Anchor Link

Field-level limits, such as the 1,000-character limit for short text, are listed in Field types.

RelatedCopy Anchor Link

• CLI reference lists the commands and the exit codes.
• JavaScript API reference lists the functions that throw these errors.
• HTTP API lists the responses for each endpoint.
• Rate limits lists every limit in the CMS.