github/spec-kit · error · ValueError

Integration manifest at {path} contains invalid JSON

Error message

Integration manifest at {path} contains invalid JSON

What it means

IntegrationManifest.load() failed to parse the manifest file as JSON (json.JSONDecodeError). Anything from trailing commas and comments to conflict markers or truncation lands here; the file must be strict JSON.

Source

Thrown at src/specify_cli/integrations/manifest.py:478

        key: str,
        project_root: Path,
        *,
        resolve_project_root: bool = True,
    ) -> IntegrationManifest:
        """Load an existing manifest from disk.

        Raises ``FileNotFoundError`` if the manifest does not exist.
        """
        inst = cls(key, project_root, resolve_project_root=resolve_project_root)
        path = inst.manifest_path
        try:
            data = json.loads(path.read_text(encoding="utf-8"))
        except UnicodeDecodeError as exc:
            raise ValueError(
                f"Integration manifest at {path} is not valid UTF-8"
            ) from exc
        except json.JSONDecodeError as exc:
            raise ValueError(
                f"Integration manifest at {path} contains invalid JSON"
            ) from exc

        if not isinstance(data, dict):
            raise ValueError(
                f"Integration manifest at {path} must be a JSON object, "
                f"got {type(data).__name__}"
            )

        files = data.get("files", {})
        if not isinstance(files, dict) or not all(
            isinstance(k, str) and isinstance(v, str) for k, v in files.items()
        ):
            raise ValueError(
                f"Integration manifest 'files' at {path} must be a "
                "mapping of string paths to string hashes"
            )

View on GitHub (pinned to bf88c9f9a8)

Solutions

Validate the file with a JSON parser to find the offset: python -m json.tool <file>
Fix the syntax error, or restore via git if the file is tracked
If unrecoverable, delete the manifest and re-run specify integration install <key> (files already on disk can be re-adopted with record_existing)

Example fix

# before
{"files": {"a": "b",}}  # trailing comma
# after
{"files": {"a": "b"}}

Defensive patterns

Strategy: validation

Validate before calling

import json
try:
    json.loads(manifest.manifest_path.read_text(encoding="utf-8"))
except json.JSONDecodeError:
    restore_or_regenerate()  # git checkout or delete + re-install

Try / catch

try:
    IntegrationManifest.load(key, root)
except ValueError as exc:
    if "invalid JSON" in str(exc):
        regenerate_manifest(key, root)
    else:
        raise

Prevention

Never put comments or trailing commas in manifest JSON
Resolve git conflicts in .specify before running the CLI
Regenerate instead of hand-fixing large corruptions

When it happens

Trigger: Loading a manifest containing YAML/JSON5 syntax (comments, single quotes), leftover git conflict markers (<<<<<<<), or a truncated file from an interrupted save(); also hand-edits that broke the structure.

Common situations: Users editing the manifest to remove a tracked file and mistyping; merge conflicts in repos that commit .specify; power loss or Ctrl-C during save().

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

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