usestrix/strix · error · ValueError

Invalid API spec '{target}': {exc}

Error message

Invalid API spec '{target}': {exc}

What it means

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.

Source

Thrown at strix/interface/scan_setup.py:158

    from a spec) and, for a ``postman://`` target, downloads the collection to a
    local file so the sandbox never needs the Postman API key.
    """
    try:
        if details.get("source") == "postman_api":
            collection_uid = str(details["collection_uid"])
            api_key = load_settings().integrations.postman_api_key or ""
            raw = fetch_postman_collection(collection_uid, api_key)
            environment_uid = str(details.get("environment_uid") or "")
            extra_variables = (
                fetch_postman_environment(environment_uid, api_key) if environment_uid else None
            )
            details["target_spec"] = write_fetched_collection(raw, collection_uid)
        else:
            raw = load_spec(str(details["target_spec"]))
            extra_variables = None
        base_urls = spec_base_urls(raw, extra_variables=extra_variables)
    except SpecParseError as exc:
        raise ValueError(f"Invalid API spec '{target}': {exc}") from None

    details["spec_title"] = spec_title(raw)
    details["base_urls"] = base_urls


def prepare_run(args: argparse.Namespace) -> None:
    """Resolve the run name, clone repos, compute diff-scope, and persist state.

    Shared by the CLI startup path and the interactive TUI setup phase (once the
    user has supplied a target via ``/target``). Mutates *args* in place and
    raises :class:`ValueError` on any preparation failure.
    """
    args.run_name = args.resume or generate_run_name(args.targets_info)

    if args.resume:
        return

    for target_info in args.targets_info:

View on GitHub (pinned to 8551339130)

Solutions

1. Validate the spec independently first: `npx @redocly/cli lint openapi.yaml` or swagger-cli validate; fix reported syntax/schema errors.
2. For Postman targets, confirm integrations.postman_api_key is configured and the collection UID is correct.
3. 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).
4. If variables/base URLs are the issue, supply the Postman environment_uid or inline variables so spec_base_urls can resolve.

Example fix

# before
$ strix -n -t './specs/broken-api.json'   # Invalid API spec

# after
$ npx @redocly/cli lint specs/broken-api.json   # fix reported errors first
$ strix -n -t './specs/broken-api.json'

from strix.tools.apispec import load_spec, spec_base_urls
from strix.tools.apispec.exceptions import SpecParseError
try:
    raw = load_spec('path/to/openapi.yaml')
    urls = spec_base_urls(raw)
except SpecParseError as e:
    print(f'spec rejected before scan: {e}')

def spec_is_loadable(path: str) -> bool:
    try:
        load_spec(path)
    except SpecParseError:
        return False
    return True

try:
    prepare_run(args)  # includes _resolve_api_spec
except ValueError as exc:
    if str(exc).startswith('Invalid API spec'):
        # validate/repair the spec externally, then retry setup
        run_spec_linter(target_spec_path)
        prepare_run(args)
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Missing Postman collection id in '{target}' (expected postma
• Path exists but is not a directory: {target}
• extra_system_prompt_context cannot override built-in scope k
• Cannot resume scan {scan_id}: agents.json has no root agent
• Invalid target '{target}': {e}

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