Troubleshooting

Troubleshooting

Read the Details first

Every service's Details view echoes the JSON path, the source endpoint URL, and the expected pattern (when set). That's usually enough to see whether you targeted the right value or the right endpoint.

Test the agent from the command line

As the site user, you can run the agent directly against one endpoint to see the raw section it produces:

~/local/lib/python3/cmk_addons/plugins/json_api/libexec/agent_json_api --help

The Explorer generates the exact --endpoint … invocation for your config — copy it and run it to see what the agent extracts before wiring up the rule.

Common symptoms

Service is UNKNOWN — "path not found"

The JSON path didn't resolve in the response.

• Confirm the path against a real sample (paste it into the Explorer).
• Watch for arrays: items.count won't work if items is a list — you need items[0].count or items[*].count.
• Keys with . or [ must be bracket-quoted: data['foo.bar'].
• See JSON paths.

All of an endpoint's services are UNKNOWN

The endpoint request failed or the response wasn't JSON. The error text is in the service output.

• Can the Checkmk server reach the URL? (Not your workstation — the site.) Try curl from the site host.
• TLS error? The cert must be valid, or disable Verify the TLS certificate for that endpoint (insecure — prefer fixing the cert).
• Timeout? Raise the endpoint's Request timeout.
• Auth failure? Check the password-store entry and the auth type.
• Note: other endpoints in the same rule keep reporting normally — only the failing endpoint's services go UNKNOWN.

A value expected to match is CRIT

The expected regex must match the value in full.

• Values are compared as they appear in JSON: true / false / null, not True / False / None.
• UP won't match "UP " (trailing space) or "Up" (case) — use e.g. (?i)up or UP\s* if needed.

Service is WARN unexpectedly

You set levels on a value that isn't numeric. The plugin flags this as WARN so the misconfiguration is visible. Remove the levels or use an expected regex instead.

No services appear after configuring the rule

• Activate changes, then run service discovery on the host.
• Confirm the rule actually applies to that host (folder/conditions).
• Confirm the MKP is enabled: mkp list should show json_api enabled.

Duplicate service names

If two fields/endpoints produce the same name, the later one gets a (2) suffix. Give them distinct Service name values instead.

Still stuck?

• Ask in Discussions → Q&A — include your Checkmk version, the (redacted) rule, and a sample response.
• Think it's a bug? Open an issue.
• Security concern? See SECURITY.md — report privately, not as a public issue.