Typeweaver

Troubleshooting

This troubleshooting guide covers the most common Typeweaver errors in spec authoring, code generation, and runtime validation. Each section shows the error message, explains what triggered it, and tells you how to fix it.

Spec authoring errors

These errors appear when typeweaver generate loads and validates your spec.

InvalidResourceNameError

Resource name 'my_resource' is invalid. Use camelCase singular nouns when
possible; PascalCase is also supported. snake_case and kebab-case are not
supported.

Cause: Resource keys in defineSpec({ resources: { ... } }) must be camelCase or PascalCase.

Fix: Rename the resource key.

// before
resources: { my_resource: { operations: [...] } }

// after
resources: { myResource: { operations: [...] } }

InvalidOperationIdError

Operation ID 'get_todo' is invalid. Use camelCase (preferred) or PascalCase.
snake_case and kebab-case are not supported.

Cause: The operationId field must be camelCase or PascalCase.

Fix: Change the operation ID.

// before
operationId: "get_todo"

// after
operationId: "GetTodo"

PathParameterMismatchError

Operation 'GetTodo' has mismatched path parameters for '/todos/:todoId'.
Path params: [todoId], request.param keys: [id].

Cause: The path parameters (:todoId) do not match the keys in request.param.

Fix: Make sure every :param in the path has a matching key in request.param, and vice versa.

// before
path: "/todos/:todoId",
request: {
  param: z.object({ id: z.string() }),
}

// after
path: "/todos/:todoId",
request: {
  param: z.object({ todoId: z.string() }),
}

DuplicateOperationIdError

Operation ID 'GetTodo' must be globally unique within a spec.

Cause: Two or more operations share the same operationId, even across different resources.

Fix: Give each operation a unique ID. A common pattern is to prefix with the resource name: GetTodo, GetUser, GetOrder.

DuplicateRouteError

Cause: Two operations share the same HTTP method and normalized path (for example, two GET /todos/:todoId operations).

Fix: Either use different paths or different HTTP methods for each operation.

DuplicateResponseNameError

Duplicate response name: 'TodoNotFoundError'

Cause: Response names are global across the entire spec. Two defineResponse(...) calls use the same name.

Fix: Choose unique names. If you intentionally reuse the same error response across operations, define it once and reference the same object in each responses array.

EmptySpecResourcesError

Spec definition must contain at least one resource.

Fix: Add at least one resource with at least one operation to your spec.

EmptyResourceOperationsError

Resource 'todo' must contain at least one operation.

Fix: Add at least one operation to the resource.

EmptyOperationResponsesError

Operation 'GetTodo' must declare at least one response.

Fix: Add at least one defineResponse(...) to the responses array.

InvalidRequestSchemaError

Operation 'GetTodo' has an invalid request.param schema definition.

Cause: A request schema is not a valid Zod type, or request.param is not a z.object(...).

Fix: Make sure request.param is always a z.object(...). Other request parts (header, query, body) must also be valid Zod schemas.

// before — param must be z.object, not z.string
request: {
  param: z.string(),
}

// after
request: {
  param: z.object({ todoId: z.string() }),
}

Derived response errors

These errors appear when derived response definitions have structural problems.

MissingDerivedResponseParentError

Derived response 'TodoNotFoundError' references missing canonical parent
'NotFoundError'.

Cause: The base response passed to defineDerivedResponse(...) is not part of any operation's responses array in the spec, or it was not created with defineResponse(...).

Fix: Make sure the parent response is included in at least one operation.

DerivedResponseCycleError

Derived response 'ErrorA' contains a cyclic lineage.

Cause: Two or more derived responses reference each other in a circular chain.

Fix: Flatten the chain so derivation only goes one direction.

CLI and config errors

TypeScript config file

TypeScript config files are no longer supported: 'typeweaver.config.ts'.
Convert the config to .js, .mjs, or .cjs, or compile it before passing --config.

Cause: Typeweaver only accepts JavaScript config files.

Fix: Rename your config to .js, .mjs, or .cjs and convert to plain JavaScript.

// typeweaver.config.mjs
export default {
  input: "./api/spec/index.ts",
  output: "./api/generated",
  plugins: ["clients", "server"],
};

Missing input or output

No input spec entrypoint provided. Use --input or specify in config file.

No output directory provided. Use --output or specify in config file.

Fix: Pass both --input and --output, or set them in your config file.

Config export problems

Configuration file must export a config object via 'export default'
or 'export const config = ...'.

Cause: The config file does not export anything Typeweaver recognizes.

Fix: Use exactly one of these export styles:

// option 1
export default { input: "...", output: "...", plugins: [...] };

// option 2
export const config = { input: "...", output: "...", plugins: [...] };

Do not export both from the same file.

Plugin not found

Failed to load plugin 'my-plugin'

Cause: Typeweaver tried to resolve the plugin name and could not find a matching package.

Fix: Check that:

  • the plugin package is installed (npm ls @rexeus/typeweaver-clients)
  • the name matches a known plugin: clients, hono, server, aws-cdk
  • for custom plugins, the import path is correct

Resolution order: @rexeus/typeweaver-{name} → @rexeus/{name} → literal string.

Spec bundling failed

Failed to bundle spec entrypoint './api/spec/index.ts' to '...'

Cause: The CLI uses rolldown to bundle your spec file before importing it. This error means the bundle step failed.

Common causes:

  • syntax errors in your spec file or its imports
  • importing a package that is not installed
  • circular imports between spec files

Fix: Check the full error output for the specific rolldown error. Fix the underlying TypeScript or import issue.

Invalid spec entrypoint

Spec entrypoint './api/spec/index.ts' must export a SpecDefinition as its
default export, named 'spec' export, or module namespace.

Cause: The bundled spec file does not export a valid spec object.

Fix: Make sure your entrypoint exports the spec:

// preferred
export const spec = defineSpec({ ... });

// also works
export default defineSpec({ ... });

Runtime errors

These errors can appear when using generated clients or validators at runtime.

RequestValidationError

Cause: A request does not match the declared schema. The error groups issues by request part.

try {
  validator.validate(request);
} catch (error) {
  if (error instanceof RequestValidationError) {
    console.log(error.headerIssues);
    console.log(error.bodyIssues);
    console.log(error.queryIssues);
    console.log(error.pathParamIssues);
  }
}

Common causes:

  • missing required fields in query, header, or body
  • wrong types (number where string was expected)
  • missing path parameters

ResponseValidationError

Cause: A handler returned a response that does not match the declared contract.

if (error instanceof ResponseValidationError) {
  console.log(error.statusCode);
  console.log(error.issues);
  console.log(error.hasStatusCodeIssues());
  console.log(error.hasResponseIssues());
}

Common causes:

  • returning a status code that is not declared in the operation
  • returning a body shape that does not match the response schema
  • missing required body or header fields in the response

UnknownResponseError

Cause: The client received a response with a status code that does not match any declared response for the operation.

Fix: Either add a response definition for that status code, or handle the unknown case in your client code.

Client NetworkError

Cause: The generated client could not reach the server.

Error codes:

  • TIMEOUT — request exceeded timeoutMs
  • ABORT — request was aborted
  • ECONNREFUSED — server is not running
  • ECONNRESET — connection was reset
  • ENOTFOUND — DNS lookup failed
  • ERR_SSL — TLS/SSL error
  • UNKNOWN — other network failure

Fix: Check that the baseUrl is correct and the server is reachable.

Client ResponseParseError

Cause: The response body could not be parsed as JSON.

Common causes:

  • server returned HTML (404 page, proxy error)
  • server returned empty body for a response that expects JSON
  • content-type mismatch

Formatting warnings

oxfmt not installed

oxfmt not installed - skipping formatting.
Install with: npm install -D oxfmt

This is a warning, not an error. Generation still completes, but the output files are not formatted.

Fix: Install oxfmt as a dev dependency:

npm install -D oxfmt

Was this page helpful?