Troubleshooting

Common Yellow Jacket problems and their expected solutions.

No configuration found

Error:

No yellow-jacket config found

Run Yellow Jacket from an application containing a configuration file.

Create one with:

yellow-jacket init

The expected file is:

yellow-jacket.config.mjs

The Yellow Jacket source repository itself intentionally has no application configuration.

No baseline found

Message:

No baseline found.
Run "yellow-jacket baseline" to create one.

Create the known-good snapshot:

yellow-jacket baseline

Then run:

yellow-jacket run

Invalid or unsupported baseline

Yellow Jacket validates an existing baseline before executing run.

For example:

Invalid baseline at ...: expected formatVersion 1, received 2.

Regenerate the baseline with the current Yellow Jacket version when the file is obsolete:

yellow-jacket baseline

If the baseline was edited manually or has merge-conflict damage, restore or regenerate it rather than bypassing validation.

Mutating request blocked

Example:

Blocked POST request to api.example.com.

Mutating requests to non-local targets are blocked by default.

For an environment that is intentionally authorized:

yellow-jacket run \
  --allow-actions

or:

yellow-jacket baseline \
  --allow-actions

Do not enable this flag for an unintended production target.

Coverage source missing

Yellow Jacket coverage requires at least one inventory.

OpenAPI:

coverage: {
  openapi:
    './openapi.json'
}

Sitemap:

coverage: {
  sitemap:
    './sitemap.xml'
}

Or combine both.

OpenAPI document rejected

Yellow Jacket supports OpenAPI 3.x documents in JSON, YAML and YML.

Verify that the document declares an OpenAPI 3.x version and a paths object. For JSON, for example:

{
  "openapi": "3.1.0",
  "paths": {}
}

Remote sitemap index rejected

Sitemap index discovery is intentionally local.

A child such as:

https://example.com/sitemap-pages.xml

is rejected because coverage discovery does not perform HTTP requests.

Use a local sitemap file instead.

Existing Git hook manager

If yellow-jacket install detects an existing core.hooksPath, it refuses to overwrite it.

Chain:

yellow-jacket run

from the existing pre-push hook.

Skip the pre-push check once

YELLOW_JACKET=0 git push

VitePress reports a dead link

When working on the Yellow Jacket documentation, VitePress checks internal links.

For example:

Found dead link /get-started

means that the referenced Markdown page does not exist yet.

Create the page rather than disabling dead-link checking.