Skip to content
XenonDocs
Esc
    GitHub
    Docs

    Errors

    Error codes, exception classes, and validation failure payloads produced by Xenon.

    On this page

    Error handling

    Xenon throws typed error classes when requests fail validation, authentication, or concurrency checks.

    TypeScript
    import { XenonError, XenonConfigError } from "xenon-cms";
    
    try {
      await xenon.create({
        collection: "posts",
        data: { title: "" },
      });
    } catch (error) {
      if (error instanceof XenonError) {
        console.error(error.code);   // e.g. "VALIDATION"
        console.error(error.status); // e.g. 400
        console.error(error.issues); // [{ path: ["title"], message: "This field is required" }]
      }
    }

    The XenonError instance includes an HTTP status code and an array of issues indicating which field paths failed.

    Error classes

    XenonError

    Base runtime exception thrown during Local API and REST operations.

    PropertyTypeDescription
    codeXenonErrorCodeStandard error code identifier.
    statusnumberCorresponding HTTP status code.
    messagestringHuman-readable explanation.
    issuesValidationIssue[] | undefinedDetailed path-specific error list for validation failures.

    XenonConfigError

    Thrown synchronously at application boot when defineConfig or defineCollection detects invalid configurations.

    • Duplicate collection slugs.
    • Reserved field keys (id, slug, status, createdAt, updatedAt, or names starting with _).
    • Invalid relationship targets.
    • Invalid slug source fields.

    Error codes

    CodeHTTP statusDescription
    NOT_FOUND404The requested collection document or file asset does not exist.
    VALIDATION400Document data failed schema validation checks or custom field rules.
    FORBIDDEN403Authenticated user lacks permission to perform the requested operation.
    UNAUTHORIZED401Missing or invalid authentication credentials.
    CONFLICT409Concurrent edit collision detected (If-Match timestamp mismatch).
    BAD_REQUEST400Malformed request body, invalid query parameters, or unsupported operation.
    PAYLOAD_TOO_LARGE413An uploaded file is larger than the collection's upload.maxFileSize.
    UNSUPPORTED_MEDIA_TYPE415An uploaded file's type isn't in upload.mimeTypes, or a request body isn't JSON or multipart form data.

    Validation issue shape

    When error.code === "VALIDATION", the issues property provides an array of specific field failures:

    TypeScript
    export type ValidationIssue = {
      path: (string | number)[];
      message: string;
    };

    Common messages include "This field is required" and custom error messages returned from field validate functions.

    Next steps