{"record":{"id":"fa282201048e425a","repo":"usestrix/strix","slug":"file-is-not-a-recognized-openapi-swagger-or-post","errorCode":null,"errorMessage":"File is not a recognized OpenAPI, Swagger, or Postman spec","messagePattern":"File is not a recognized OpenAPI, Swagger, or Postman spec","errorType":"exception","errorClass":"SpecParseError","httpStatus":null,"severity":"error","filePath":"strix/utils/api_spec.py","lineNumber":231,"sourceCode":"def spec_base_urls(\n    raw: dict[str, Any],\n    *,\n    extra_variables: dict[str, str] | None = None,\n) -> list[str]:\n    \"\"\"Return the absolute base URLs a spec declares, for scope authorization.\n\n    Relative and unresolved-template URLs are dropped: an unusable value would\n    otherwise be authorized as an in-scope host. Callers pair the spec with an\n    explicit ``--target`` host when the spec declares none.\n    \"\"\"\n    spec_format = classify_spec(raw)\n    if spec_format == \"openapi\":\n        return _openapi_base_urls(raw)\n    if spec_format == \"swagger\":\n        return _swagger_base_urls(raw)\n    if spec_format == \"postman\":\n        return _postman_base_urls(raw, extra_variables)\n    raise SpecParseError(\"File is not a recognized OpenAPI, Swagger, or Postman spec\")\n\n\nPOSTMAN_API_BASE = \"https://api.getpostman.com\"\n_POSTMAN_FETCH_TIMEOUT = 30\n\n\ndef _postman_api_json(url: str, api_key: str, label: str) -> dict[str, Any]:\n    \"\"\"GET a Postman API resource and return the parsed JSON payload.\n\n    Raises :class:`SpecParseError` with an actionable message on auth, network,\n    or shape errors.\n    \"\"\"\n    if not api_key:\n        raise SpecParseError(\n            \"POSTMAN_API_KEY is not set. Export a Postman API key (PMAK-…) to \"\n            \"fetch from the Postman API, or pass a local collection file instead.\",\n        )\n    try:","sourceCodeStart":213,"sourceCodeEnd":249,"githubUrl":"https://github.com/usestrix/strix/blob/85513391305171ecc6faffe03da4a8bda5e3febb/strix/utils/api_spec.py#L213-L249","documentation":"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').","triggerScenarios":"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.","commonSituations":"Assuming any JSON/YAML API description works; exporting the wrong artifact from Postman (environment instead of collection); older Swagger 1.x files.","solutions":["Convert the file to OpenAPI 3.x (key 'openapi': '3.x.y' at the root)","For Postman, export the collection itself (has 'info._postman_id' and 'item'), not an environment","For Postman collections missing the id, ensure the export is v2.1 schema format"],"exampleFix":"# before\n{\"_type\": \"export\", \"__export_format\": 4, \"resources\": [...]}  # Insomnia\n\n# after\n{\"openapi\": \"3.0.3\", \"info\": {\"title\": \"API\", \"version\": \"1.0\"}, \"paths\": {}}","handlingStrategy":"validation","validationCode":"from strix.utils.api_spec import classify_spec\n\nfmt = classify_spec(load_spec(path))\nif fmt is None:\n    raise ValueError(\"unsupported spec; convert to OpenAPI 3.x or export a Postman collection\")","typeGuard":"def is_recognized_spec(raw: dict) -> bool:\n    return (\n        isinstance(raw.get(\"openapi\"), str)\n        or str(raw.get(\"swagger\", \"\")).startswith(\"2\")\n        or (isinstance(raw.get(\"info\"), dict) and (\"_postman_id\" in raw[\"info\"] or \"item\" in raw))\n    )","tryCatchPattern":"try:\n    urls = spec_base_urls(raw)\nexcept SpecParseError as e:\n    if \"not a recognized\" in str(e):\n        convert the source to OpenAPI 3 (e.g. with api-spec-converter) and retry","preventionTips":["Standardize on OpenAPI 3.x specs in your pipeline","From Postman, always export Collection v2.1 JSON, never an environment file"],"tags":["api-spec","unsupported-format","configuration"],"backgroundTag":null,"analyzedSha":"85513391305171ecc6faffe03da4a8bda5e3febb","analyzedAt":"2026-08-15T05:03:57.275Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}