# Troubleshooting

Source: https://apigenie.pl/docs/troubleshooting

One section per symptom, with what the message means and what to change. The questions teams ask
before a command runs are on the [FAQ](/docs/faq).

## apigenie is not found after npm install -g

The directory npm installs global commands in isn't on the `PATH`. `npm prefix -g` prints the
prefix: the commands are in its `bin` directory on macOS and Linux, and in the prefix itself on
Windows. Add it to the `PATH` and open a new terminal, or run the CLI without a global install
with `npx @mykulyak/api-genie --version`. The other channels put the tools in a directory that is
on the `PATH` already ([Quickstart](/docs/quickstart#install)).

## A command stops with "unknown property" or "Unsupported configuration version"

The configuration file is checked against its schema before any command reads it, whichever
command runs and whichever section is wrong, and the command stops with exit status 2:

```text
apigenie.yaml:4:12: /commands/lint/rulez: unknown property 'rulez'; did you mean 'rules'?
```

The message names the file, the line, the JSON pointer of the value and, for a misspelled key,
the closest known name. `version` has to be the string `'1.0'`: in YAML, `version: 1.0` is a
number. The file is found in the current directory or a parent up to the root of the repository,
so a broken file higher up stops the commands below it; `--no-config` runs the command without
any file to tell the two apart, and
[`apigenie config check FILE`](/docs/reference/cli/config) checks a file without running
anything. [Where apigenie.yaml is found](/docs/concepts/where-the-configuration-is-found) has
the details.

## A rule reports an issue in a document that is valid

A rule is a convention, not the specification: a valid document can still miss a description or
name a tag twice. Each issue names its rule, and the rule's page in the
[linter rules](/docs/linter) says what it checks and why. If the convention isn't yours, change
the rule's severity or turn it off under `commands.lint.rules`; if it holds everywhere but one
place, disable it there with `x-apigenie-lint-disable` on the object
([disabling rules in a document](/docs/reference/cli/lint#disabling-rules-in-a-document)):

```yaml
version: '1.0'
commands:
  lint:
    rules:
      info-defined: off
```

If the rule is wrong about the document, open an issue with the document and the rule's id.

## The mock answers 404 or 405

The paths of the document are served under the path of its first server (`/v1` for
`https://api.example.com/v1`) and as they are. A 404 is a path the document doesn't have, a 405 a
method the path doesn't declare, and the problem details name the method and the path the mock
looked for. Check the `servers` of the document and `--base-path`, which replaces the prefix;
with `server.strict_base_path` the paths are served only under it. The
[dashboard](/docs/reference/server/dashboard) lists the routes the mock serves.
[How the mock picks a response](/docs/concepts/how-the-mock-picks-a-response) walks through the
routing and what follows.

## The mock answers 422 to a request my client considers valid

The request is checked against its operation before an answer is chosen, and the problem details
list what failed, such as `path.id: expected type integer, found string`. The client and the
document disagree, which is what the check is for; if the document is wrong, fix it. To see the
finding without refusing the request, set `validation.request: log` in the configuration: the
request is answered and the finding goes into the `X-Apigenie-Mock-Violations` headers and the
log. A `format` the document uses beyond the [format registry](/docs/reference/cli/formats) is
declared in `openapi.custom_formats` of the configuration, and `validation.formats: false` turns
the format checks off ([Validation and security](/docs/reference/server/validation)).

## The validating proxy reports violations the team disputes

Each violation names its check and its severity. A check can be re-rated or turned off in
`contract.severity`; `response.header.undefined` is off unless you turn it on. By default the
proxy reports and changes nothing, and `--fail-on errors` fails the run on errors only, not on
warnings or notes. [What the validating proxy checks](/docs/concepts/what-the-proxy-checks)
explains the checks and the severities; the
[contract testing](/docs/reference/server/contract-testing) page lists them.

## apigenie diff rates a deliberate change as breaking

The rating comes from the rules of the standard, and `--report detailed` shows the node type and
the property that rated each change. To let a deliberate removal through, announce it first:
mark the element `deprecated: true` with an `x-sunset` date and remove it after the date, which
the recommended rules rate as non-breaking; in a Protobuf file, reserve the number of a removed
field. To change a rating for good, set the rule's severity under `commands.diff.rules`.
[Accepting a breaking change](/docs/reference/cli/diff/rules#accepting-a-breaking-change) has
the four ways, and the tables of the recommended rules.

## Generated code doesn't compile

- **The toolchain.** Each target's page names what the generated code needs: Java 17 and Maven
  for `client java`, Node.js 18 or later for `client fetch`, Python 3.10 or later with pydantic
  2.11 or later for `client python`, .NET 8 for `client csharp` and `server aspnet`, Elixir 1.18
  or later for the Elixir targets ([apigenie-generator](/docs/reference/generator)).
- **The version.** The inside of generated code can change in a minor release, so a file
  generated by one version next to files generated by another can fail to compile. Regenerate
  everything with one version, and pin that version or commit the generated code
  ([compatibility](/docs/reference/cli/compatibility#what-it-doesnt-cover)).
- **The document.** A document that references other files is bundled first with
  [`apigenie bundle`](/docs/reference/cli/bundle), and a Swagger 2.0 document converted with
  [`apigenie convert`](/docs/reference/cli/convert). Lint the document before generating: a
  clean contract gives cleaner code.
- **Still failing.** Open an issue with the document, or a reduced one, the command line and the
  version: a document the generator accepts and then writes code that doesn't compile is a bug.

## apigenie test or the proxy can't reach an HTTPS server

A certificate the system doesn't trust is given with `--ca-cert FILE` (repeatable), and a server
that asks for a client certificate gets it with `--client-cert` and `--client-key`; `--insecure`
skips the verification of the server's certificate, and the traffic stays encrypted. The tools
connect directly and don't read `HTTP_PROXY` or `HTTPS_PROXY`, so a server reachable only
through a proxy isn't reachable for them ([test](/docs/reference/cli/test#options),
[TLS](/docs/reference/server/tls)).