{"record":{"id":"8a9973520ab9418f","repo":"usestrix/strix","slug":"invalid-api-spec-target-exc","errorCode":null,"errorMessage":"Invalid API spec '{target}': {exc}","messagePattern":"Invalid API spec '(.+?)': (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"strix/interface/scan_setup.py","lineNumber":158,"sourceCode":"    from a spec) and, for a ``postman://`` target, downloads the collection to a\n    local file so the sandbox never needs the Postman API key.\n    \"\"\"\n    try:\n        if details.get(\"source\") == \"postman_api\":\n            collection_uid = str(details[\"collection_uid\"])\n            api_key = load_settings().integrations.postman_api_key or \"\"\n            raw = fetch_postman_collection(collection_uid, api_key)\n            environment_uid = str(details.get(\"environment_uid\") or \"\")\n            extra_variables = (\n                fetch_postman_environment(environment_uid, api_key) if environment_uid else None\n            )\n            details[\"target_spec\"] = write_fetched_collection(raw, collection_uid)\n        else:\n            raw = load_spec(str(details[\"target_spec\"]))\n            extra_variables = None\n        base_urls = spec_base_urls(raw, extra_variables=extra_variables)\n    except SpecParseError as exc:\n        raise ValueError(f\"Invalid API spec '{target}': {exc}\") from None\n\n    details[\"spec_title\"] = spec_title(raw)\n    details[\"base_urls\"] = base_urls\n\n\ndef prepare_run(args: argparse.Namespace) -> None:\n    \"\"\"Resolve the run name, clone repos, compute diff-scope, and persist state.\n\n    Shared by the CLI startup path and the interactive TUI setup phase (once the\n    user has supplied a target via ``/target``). Mutates *args* in place and\n    raises :class:`ValueError` on any preparation failure.\n    \"\"\"\n    args.run_name = args.resume or generate_run_name(args.targets_info)\n\n    if args.resume:\n        return\n\n    for target_info in args.targets_info:","sourceCodeStart":140,"sourceCodeEnd":176,"githubUrl":"https://github.com/usestrix/strix/blob/85513391305171ecc6faffe03da4a8bda5e3febb/strix/interface/scan_setup.py#L140-L176","documentation":"Raised in _resolve_api_spec (strix/interface/scan_setup.py:158) when an API-spec target (OpenAPI/Swagger file or Postman collection UID) fails to load or parse: fetch_postman_collection/load_spec raises SpecParseError, which is converted with `from None` into a user-facing ValueError. Base URLs and the spec title are extracted afterwards, so any structural spec problem surfaces here.","triggerScenarios":"Passing -t with an OpenAPI file containing invalid YAML/JSON or missing the expected structure; a Postman collection UID that is wrong, unreachable, or fetched without a valid postman_api_key; spec files with unresolved $refs or variables when no environment is supplied.","commonSituations":"Hand-edited or auto-generated specs that are not valid OpenAPI; Postman API key missing in settings (integrations.postman_api_key) so the fetch returns an error payload; local spec path typos; specs using features the parser rejects.","solutions":["Validate the spec independently first: `npx @redocly/cli lint openapi.yaml` or swagger-cli validate; fix reported syntax/schema errors.","For Postman targets, confirm integrations.postman_api_key is configured and the collection UID is correct.","Check the spec path resolves and the file is valid YAML/JSON (python -c 'import yaml,sys;yaml.safe_load(open(sys.argv[1]))' spec.yaml).","If variables/base URLs are the issue, supply the Postman environment_uid or inline variables so spec_base_urls can resolve."],"exampleFix":"# before\n$ strix -n -t './specs/broken-api.json'   # Invalid API spec\n\n# after\n$ npx @redocly/cli lint specs/broken-api.json   # fix reported errors first\n$ strix -n -t './specs/broken-api.json'","handlingStrategy":"validation","validationCode":"from strix.tools.apispec import load_spec, spec_base_urls\nfrom strix.tools.apispec.exceptions import SpecParseError\ntry:\n    raw = load_spec('path/to/openapi.yaml')\n    urls = spec_base_urls(raw)\nexcept SpecParseError as e:\n    print(f'spec rejected before scan: {e}')","typeGuard":"def spec_is_loadable(path: str) -> bool:\n    try:\n        load_spec(path)\n    except SpecParseError:\n        return False\n    return True","tryCatchPattern":"try:\n    prepare_run(args)  # includes _resolve_api_spec\nexcept ValueError as exc:\n    if str(exc).startswith('Invalid API spec'):\n        # validate/repair the spec externally, then retry setup\n        run_spec_linter(target_spec_path)\n        prepare_run(args)\n    else:\n        raise","preventionTips":["Lint OpenAPI files (redocly/swagger-cli) before passing them as targets.","Configure integrations.postman_api_key when using Postman UIDs.","Keep specs self-contained or supply the needed environment variables."],"tags":["api-spec","openapi","postman","validation"],"backgroundTag":null,"analyzedSha":"85513391305171ecc6faffe03da4a8bda5e3febb","analyzedAt":"2026-08-15T05:03:57.275Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}