usestrix/strix · error · SpecParseError

File is not a recognized OpenAPI, Swagger, or Postman spec

Error message

File is not a recognized OpenAPI, Swagger, or Postman spec

What it means

SpecParseError raised by spec_base_urls (and callers of classify_spec) when a loaded mapping matches none of the recognized formats. Classification checks: string 'openapi' key, 'swagger' starting with '2', or a Postman shape ('info._postman_id' or a top-level 'item').

Source

Thrown at strix/utils/api_spec.py:231

def spec_base_urls(
    raw: dict[str, Any],
    *,
    extra_variables: dict[str, str] | None = None,
) -> list[str]:
    """Return the absolute base URLs a spec declares, for scope authorization.

    Relative and unresolved-template URLs are dropped: an unusable value would
    otherwise be authorized as an in-scope host. Callers pair the spec with an
    explicit ``--target`` host when the spec declares none.
    """
    spec_format = classify_spec(raw)
    if spec_format == "openapi":
        return _openapi_base_urls(raw)
    if spec_format == "swagger":
        return _swagger_base_urls(raw)
    if spec_format == "postman":
        return _postman_base_urls(raw, extra_variables)
    raise SpecParseError("File is not a recognized OpenAPI, Swagger, or Postman spec")


POSTMAN_API_BASE = "https://api.getpostman.com"
_POSTMAN_FETCH_TIMEOUT = 30


def _postman_api_json(url: str, api_key: str, label: str) -> dict[str, Any]:
    """GET a Postman API resource and return the parsed JSON payload.

    Raises :class:`SpecParseError` with an actionable message on auth, network,
    or shape errors.
    """
    if not api_key:
        raise SpecParseError(
            "POSTMAN_API_KEY is not set. Export a Postman API key (PMAK-…) to "
            "fetch from the Postman API, or pass a local collection file instead.",
        )
    try:

View on GitHub (pinned to 8551339130)

Solutions

1. Convert the file to OpenAPI 3.x (key 'openapi': '3.x.y' at the root)
2. For Postman, export the collection itself (has 'info._postman_id' and 'item'), not an environment
3. For Postman collections missing the id, ensure the export is v2.1 schema format

Example fix

# before
{"_type": "export", "__export_format": 4, "resources": [...]}  # Insomnia

# after
{"openapi": "3.0.3", "info": {"title": "API", "version": "1.0"}, "paths": {}}

from strix.utils.api_spec import classify_spec

fmt = classify_spec(load_spec(path))
if fmt is None:
    raise ValueError("unsupported spec; convert to OpenAPI 3.x or export a Postman collection")

def is_recognized_spec(raw: dict) -> bool:
    return (
        isinstance(raw.get("openapi"), str)
        or str(raw.get("swagger", "")).startswith("2")
        or (isinstance(raw.get("info"), dict) and ("_postman_id" in raw["info"] or "item" in raw))
    )

try:
    urls = spec_base_urls(raw)
except SpecParseError as e:
    if "not a recognized" in str(e):
        convert the source to OpenAPI 3 (e.g. with api-spec-converter) and retry

When it happens

Trigger: Passing an Insomnia/REST Client export, a RAML or API Blueprint file converted to YAML, a Postman environment file (values, not a collection), or a hand-written mapping without 'openapi'/'swagger' keys.

Common situations: Assuming any JSON/YAML API description works; exporting the wrong artifact from Postman (environment instead of collection); older Swagger 1.x files.

Related errors

• Cannot read spec {p}: {exc}
• extra_system_prompt_context cannot override built-in scope k
• No LLM model configured. Set STRIX_LLM env or pass model= to
• strix_image is not configured. Set it in ~/.strix/cli-config
• Invalid API spec '{target}': {exc}

AI-assisted analysis of usestrix/strix@8551339130 (2026-08-15). Data as JSON: /api/errors/fa282201048e425a. Report an issue: GitHub.