rohitg00/ai-engineering-from-scratch · error · SchemaError

: unexpected fields

Error message

{path}: unexpected fields {unexpected}

What it means

AdditionalProperties-style branch of the mini JSON-Schema validator: the object at the given path contains keys that are neither in the schema's properties nor its additional allow-list. The validator enforces a closed object shape, so extra fields are rejected as schema drift, not ignored.

Solutions

1. Remove or rename the unexpected keys listed in the error
2. Add the new fields to the schema when the document format legitimately grew
3. Gate schema evolution behind a version bump so old readers reject loudly
4. Normalize/strip unknown keys at ingestion if the design prefers forward compatibility

When it happens

Trigger: Thrown at phases/14-agent-engineering/34-repo-memory-and-state/code/main.py:90 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of rohitg00/ai-engineering-from-scratch@39ea8a1c6d (2026-08-26). Data as JSON: /api/errors/19e7bb251494abb1. Report an issue: GitHub.

Appendix: source

Thrown at phases/14-agent-engineering/34-repo-memory-and-state/code/main.py:90

            return True
    return False


def validate(value: Any, schema: dict[str, Any], path: str = "$") -> None:
    if "type" in schema and not _check_type(value, schema["type"]):
        raise SchemaError(f"{path}: expected {schema['type']}, got {type(value).__name__}")
    if "enum" in schema and value not in schema["enum"]:
        raise SchemaError(f"{path}: {value!r} not in {schema['enum']}")
    if "pattern" in schema and isinstance(value, str) and not re.match(schema["pattern"], value):
        raise SchemaError(f"{path}: {value!r} does not match /{schema['pattern']}/")
    if isinstance(value, dict):
        for key in schema.get("required", []):
            if key not in value:
                raise SchemaError(f"{path}: missing required field {key!r}")
        properties = schema.get("properties", {})
        unexpected = sorted(set(value.keys()) - set(properties.keys()))
        if unexpected:
            raise SchemaError(f"{path}: unexpected fields {unexpected}")
        for key, sub in properties.items():
            if key in value:
                validate(value[key], sub, f"{path}.{key}")
    if isinstance(value, list) and "items" in schema:
        for idx, item in enumerate(value):
            validate(item, schema["items"], f"{path}[{idx}]")


def atomic_write(path: Path, content: str) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    fd, tmp_name = tempfile.mkstemp(prefix=path.name + ".", dir=path.parent)
    try:
        with os.fdopen(fd, "w") as fh:
            fh.write(content)
            fh.flush()
            os.fsync(fh.fileno())
        os.replace(tmp_name, path)
    except Exception:

View on GitHub (pinned to 39ea8a1c6d)