github/spec-kit · error · TemplateResolutionError

Failed to parse extension registry {registry}: {exc}

Error message

Failed to parse extension registry {registry}: {exc}

What it means

_enforce_workflow_yaml_size() is the final in-memory gate: after a workflow YAML payload is fully read (download or local content), len(data) is compared against _MAX_WORKFLOW_YAML_BYTES (5 MiB) and ValueError is raised if exceeded. It catches anything the network checks missed — decoded decompressed bodies, locally supplied content, or data assembled by callers.

Source

Thrown at scripts/python/common.py:254

            if p.is_dir() and _is_safe_component(p.name)
        )
    except OSError:
        return []


def _sorted_extension_ids(extensions_dir: Path) -> list[str]:
    registry = extensions_dir / ".registry"
    registered_ids: set[str] = set()
    extensions: dict[object, object] = {}
    if os.path.lexists(registry):
        if not registry.is_file():
            raise TemplateResolutionError(
                f"Invalid extension registry {registry}: not a regular file"
            )
        try:
            data = json.loads(registry.read_text(encoding="utf-8"))
        except (OSError, UnicodeError, json.JSONDecodeError) as exc:
            raise TemplateResolutionError(
                f"Failed to parse extension registry {registry}: {exc}"
            ) from exc
        if not isinstance(data, dict):
            raise TemplateResolutionError(
                f"Invalid extension registry {registry}: root must be a mapping"
            )
        raw_extensions = data.get("extensions", {})
        if not isinstance(raw_extensions, dict):
            raise TemplateResolutionError(
                f"Invalid extension registry {registry}: "
                "'extensions' must be a mapping"
            )
        extensions = raw_extensions
        registered_ids = {
            ext_id for ext_id in extensions if isinstance(ext_id, str)
        }

    ranked: list[tuple[int, str]] = []

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Shrink the workflow YAML: move large inline payloads (scripts, base64 blobs) to referenced files within the bundle
2. Regenerate the workflow without embedded assets and validate with `wc -c workflow.yaml`
3. If serving over HTTP, disable transfer compression for this asset so wire checks see the true size earlier with a clearer error
4. Split the workflow into multiple smaller workflows

Example fix

# before
# workflow.yaml embeds a 6 MiB base64 dataset in `steps.data`

# after
# move the dataset to an adjacent file and reference it
steps:
  - run: scripts/load_data.py  # reads data.bin next to workflow.yaml

MAX = 5 * 1024 * 1024

if len(workflow_yaml_bytes) > MAX:
    raise ValueError(f'workflow YAML is {len(workflow_yaml_bytes)} bytes; limit is {MAX}')
# only then pass to the staging pipeline

try:
    stage_workflow(workflow_id, yaml_bytes)
except ValueError as e:
    if 'workflow size limit' in str(e):
        raise SystemExit('workflow YAML too large; externalize inline blobs and retry') from e
    raise

When it happens

Trigger: Any code path that stages a workflow YAML whose bytes exceed 5 MiB: a downloaded body that was gzip/deflate encoded so its decoded size exceeded the wire checks, or a caller passing a large local workflow definition into the staging pipeline.

Common situations: Content-Encoding (gzip/brotli) responses whose decoded size exceeds 5 MiB while wire checks passed; workflows embedding huge inline data URIs or pasted blobs; generated workflows from templates with unbounded inline content.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• ERROR: Feature directory not found. Set SPECIFY_FEATURE_DIRE
• Invalid extension registry {registry}: not a regular file
• Malformed catalog config at {path}: expected a mapping at th
• Malformed catalog config at {path}: 'catalogs' must be a lis
• Malformed catalog config at {path}: each catalog entry must

AI-assisted analysis of github/spec-kit@bf88c9f9a8 (2026-08-14). Data as JSON: /api/errors/7e0e04f3ed508dfa. Report an issue: GitHub.