Skip to main content
@craft-ts
Beta

Deployment diagnostics#

Experimental

Codes can be added, and their messages can change, between minor versions. Do not match on a message in a CI script: match on the code field of the --json report, which is the part meant to be stable.

Every problem craft-ts check reports carries a code, the concerned runtime or platform, a location, what is wrong and what to change. This page is the reference for the codes; it is verified against the checker, so a code cannot ship undocumented.

error fails the check and the command exits with 1. warning is printed and the command still succeeds — warnings cover the heuristics, such as scanning sources for environment variable reads, where a false positive must not block a deployment.

Read a report with --json when a machine consumes it:

bash
npx craft-ts check --config apps/demo-ssr/craft.deploy.ts --json

Codes#

CRAFT_DEPLOY_ARTIFACT_MISSING#

The artefact directory does not exist.

  • Cause — The directory the provider would publish has not been produced.

  • Fix — Run the declared build command before checking the artefact.

CRAFT_DEPLOY_ARTIFACT_NO_ENTRY#

The artefact has no browser entry point.

  • Cause — The public directory contains no index.html.

  • Fix — Check the build output directory declared in client.outDir.

CRAFT_DEPLOY_ARTIFACT_NO_JAVASCRIPT#

The artefact contains no JavaScript.

  • Cause — The public directory has no .js or .mjs file, which means the build produced nothing executable.

  • Fix — Check the build command and its output directory.

CRAFT_DEPLOY_ARTIFACT_SOURCE_MAP#

The artefact ships source maps.

  • Cause — The source map policy is forbidden and the public directory contains .map files.

  • Fix — Disable source maps in the production build, or relax artifact.sourceMaps.

CRAFT_DEPLOY_CONFIG_LOAD_FAILED#

The deployment manifest could not be imported.

  • Cause — Loading the manifest threw, or the serialised manifest is not valid JSON. A TypeScript manifest also fails when the running Node cannot strip types and TypeScript is not installed.

  • Fix — Fix the thrown error, or run the CLI under a TypeScript loader, or commit a craft.deploy.json produced by the build.

CRAFT_DEPLOY_CONFIG_NOT_FOUND#

No deployment manifest found.

  • Cause — No craft.deploy.ts, craft.deploy.mjs, craft.deploy.js or craft.deploy.json was found in the checked directory.

  • Fix — Create a manifest with defineCraftDeployment or point the CLI at one with --config.

CRAFT_DEPLOY_CONFIG_NO_DEFAULT_EXPORT#

The deployment manifest has no default export.

  • Cause — The module loaded but exposes no default export to read.

  • Fix — Add export default defineCraftDeployment({ ... }).

CRAFT_DEPLOY_DEPLOY_NOT_CONFIRMED#

A deployment was requested without confirmation.

  • Cause — craft-ts deploy mutates an infrastructure, so it refuses to run until the plan has been approved explicitly.

  • Fix — Review craft-ts deploy preview, then pass --yes to apply it.

CRAFT_DEPLOY_ENV_NAME_INVALID#

Invalid environment variable name.

  • Cause — A declared name is not an upper snake case identifier, which several platforms reject.

  • Fix — Rename the variable to UPPER_SNAKE_CASE.

CRAFT_DEPLOY_ENV_UNDECLARED#

An environment variable is read but not declared.

  • Cause — The module graph of the runtime entry reads a variable the manifest does not list, so no provider can know it must be set.

  • Fix — Declare the variable in env, or stop reading it from the runtime entry.

CRAFT_DEPLOY_ENV_VALUE_FORBIDDEN#

An environment variable carries a value.

  • Cause — The manifest is committed and read by every provider, so it declares names and requirements only.

  • Fix — Remove the value and provide it through the CI or the provider secret store.

CRAFT_DEPLOY_FUNCTION_ID_DUPLICATE#

A server-function identifier is declared twice.

  • Cause — The identifier is the routing key of the protocol, so a duplicate makes the exposed contract ambiguous.

  • Fix — Keep one declaration per identifier.

CRAFT_DEPLOY_FUNCTION_ID_UNKNOWN#

A declared server-function identifier is not in the registry entry.

  • Cause — The identifier does not appear in the module graph of functions.entry.

  • Fix — Register the function in the entry, or remove the identifier from the manifest.

CRAFT_DEPLOY_HEALTH_PATH_MISSING#

The health route is not served by the SSR entry.

  • Cause — The path declared as server.healthPath was not found in the module graph of the SSR entry.

  • Fix — Serve the declared path, or align the manifest with the path the server exposes.

CRAFT_DEPLOY_MANIFEST_INVALID_FIELD#

A manifest field has an invalid value.

  • Cause — The field exists but its type or its shape does not match the contract.

  • Fix — Correct the value reported by path; the message states what was expected.

CRAFT_DEPLOY_MANIFEST_MISSING_FIELD#

A required manifest field is missing.

  • Cause — A field the runtime or the providers need is absent.

  • Fix — Add the field reported by path.

CRAFT_DEPLOY_MANIFEST_NOT_AN_OBJECT#

The manifest is not an object.

  • Cause — The default export or the parsed JSON is not a plain object.

  • Fix — Export the object returned by defineCraftDeployment.

CRAFT_DEPLOY_MANIFEST_SECTION_MISSING#

The runtime section is missing.

  • Cause — Each runtime requires its own section: static and client, server, worker or lambda.

  • Fix — Add the section the runtime requires.

CRAFT_DEPLOY_MANIFEST_SECTION_UNEXPECTED#

A section does not belong to this runtime.

  • Cause — A section of another runtime is present; nothing would ever execute it.

  • Fix — Remove the section, or change the runtime to the one that uses it.

CRAFT_DEPLOY_MANIFEST_UNKNOWN_PLATFORM#

Unknown platform.

  • Cause — platform is not part of the documented platform list.

  • Fix — Pick a supported platform, or open an issue to add it to the matrix.

CRAFT_DEPLOY_MANIFEST_UNKNOWN_RUNTIME#

Unknown runtime.

  • Cause — runtime is not one of static, node, worker or lambda.

  • Fix — Pick one of the four supported runtimes.

CRAFT_DEPLOY_NODE_BUILTIN_IMPORT#

A Node built-in is imported by a Worker or Lambda entry.

  • Cause — The module graph reachable from the entry imports a Node built-in such as node:fs or node:http, which a Worker runtime does not provide.

  • Fix — Replace the built-in with a Web API, or move the code behind a platform adapter that the Worker entry does not import.

CRAFT_DEPLOY_PATH_MISSING#

A declared path does not exist.

  • Cause — An entry point, an output directory or a configuration file declared by the manifest is absent from disk.

  • Fix — Run the build that produces it, or correct the path in the manifest.

CRAFT_DEPLOY_PLATFORM_MISMATCH#

The requested platform is not the manifest platform.

  • Cause — --platform was passed with a value the manifest does not declare.

  • Fix — Drop the flag, or change platform in the manifest.

CRAFT_DEPLOY_PROTOCOL_VERSION_UNSUPPORTED#

Unsupported manifest protocol version.

  • Cause — The serialised manifest was produced by another version of the protocol.

  • Fix — Rebuild the manifest with the current CraftTS tooling, or follow the migration notes.

CRAFT_DEPLOY_PROVIDER_CAPABILITY_MISSING#

The provider does not support this runtime.

  • Cause — The capability required by the runtime, and by the static mode when relevant, is not offered by the provider.

  • Fix — Choose a provider that declares the capability, or change the runtime or the static mode.

CRAFT_DEPLOY_PROVIDER_CREDENTIALS_MISSING#

The provider has no credentials.

  • Cause — A credential the platform requires is absent from the environment. The tooling never stores one, so it can only report the name it expected.

  • Fix — Export the named variable in the shell or the CI secret store, then run the command again.

CRAFT_DEPLOY_PROVIDER_INVALID_MODULE#

The provider package does not export a provider.

  • Cause — The module loaded but exposes no createCraftDeploymentProvider factory.

  • Fix — Export createCraftDeploymentProvider(options?) returning a CraftDeploymentProvider.

CRAFT_DEPLOY_PROVIDER_NOT_INSTALLED#

The provider package is not installed.

  • Cause — The CLI resolves a provider from @craft-ts/deploy-<name> at run time, and that package is absent from the project.

  • Fix — Install the provider package, or point --provider-module at the module that exports it.

CRAFT_DEPLOY_PROVIDER_PLATFORM_UNSUPPORTED#

The provider does not target this platform.

  • Cause — The provider cannot deploy to the platform declared by the manifest.

  • Fix — Choose a provider that targets the platform, or change the platform.

CRAFT_DEPLOY_PROVIDER_STATE_UNAVAILABLE#

The provider state cannot be read.

  • Cause — An infrastructure provider reconciles against a recorded state; without it, a deployment cannot tell a creation from an update.

  • Fix — Make the state backend reachable, or initialise it for this stage before deploying.

CRAFT_DEPLOY_PROVIDER_TOOLCHAIN_MISSING#

A tool the provider drives is missing.

  • Cause — The provider shells out to a CLI or imports a runtime package that is not installed.

  • Fix — Install the reported tool, or choose a provider that does not need it.

CRAFT_DEPLOY_PROVIDER_UNKNOWN#

Unknown provider.

  • Cause — The provider name is absent from the capability matrix.

  • Fix — Use a documented provider name, or register the provider before checking.

CRAFT_DEPLOY_PROVIDER_UNSUPPORTED_RESOURCE#

The provider has no resource for this part of the manifest.

  • Cause — The runtime, the platform or a declared binding maps to nothing the provider knows how to create.

  • Fix — Remove the declaration, or deploy that part with a provider that supports it.

CRAFT_DEPLOY_READY_PATH_MISSING#

The readiness route is not served by the SSR entry.

  • Cause — The path declared as server.readyPath was not found in the module graph of the SSR entry.

  • Fix — Serve the declared path, or align the manifest with the path the server exposes.

CRAFT_DEPLOY_RUNTIME_MISMATCH#

The requested runtime is not the manifest runtime.

  • Cause — --runtime was passed with a value the manifest does not declare.

  • Fix — Drop the flag, or change runtime in the manifest.

CRAFT_DEPLOY_RUNTIME_PLATFORM_INCOMPATIBLE#

This platform cannot execute this runtime.

  • Cause — The platform has no execution shape for the declared runtime, for instance a lambda runtime on Cloudflare.

  • Fix — Change the runtime or the platform; the compatibility matrix lists the supported pairs.

CRAFT_DEPLOY_SPA_FALLBACK_MISSING#

The SPA fallback document is missing from the client output.

  • Cause — A spa deployment answers unknown paths with the fallback document, which is absent from the built output.

  • Fix — Build the client, or correct static.fallback.

CRAFT_DEPLOY_SSG_ROUTES_MISSING#

The SSG mode declares no route.

  • Cause — A ssg deployment pre-renders one HTML file per route and the route list is empty.

  • Fix — List the routes in static.routes, or switch the mode to spa.

CRAFT_DEPLOY_SSG_ROUTE_NOT_RENDERED#

A declared SSG route has no pre-rendered document.

  • Cause — The artefact contains neither <route>.html nor <route>/index.html for a route listed in static.routes.

  • Fix — Run the pre-render step for that route, or remove it from static.routes.

CRAFT_DEPLOY_SSG_ROUTE_NOT_STATIC#

An SSG route cannot be pre-rendered.

  • Cause — The route is not an absolute literal path: it carries a :param, a wildcard or a query string, so no single HTML file represents it.

  • Fix — Expand the route into its literal paths, or declare it in static.serverRoutes.

Search