How do I install the Troubleshooting skill?

Run npx skillmds@latest add pranavj17/troubleshooting in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Troubleshooting safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: WARNING. Capability flags: makes network calls, reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Troubleshooting?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Troubleshooting free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Troubleshooting?

Pranavj17 (@pranavj17) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Troubleshooting by pranavj17 — Agent Skill

Name: Troubleshooting
Rating: 4.2 (5 reviews)
Author: Pranavj17

Troubleshooting

Use when Graylog MCP tools return errors (connection refused, 401, target not found, empty results when results are expected). Diagnoses connectivity, auth, and configuration. Triggers on graylog tool failures, "connection refused", "401", "target not found", "graylog isn't returning anything".

Pranavj17 Updated Sep 10, 2026

File contents

Graylog MCP — Troubleshooting

Use this skill when Graylog MCP tool calls fail or return nothing unexpectedly.

Step 1 — Always start with `get_system_info`

If any other tool fails, call get_system_info first. It tells you whether the server is reachable and the credentials are valid. If it returns successfully, the connection is fine and the issue is in the query.

If get_system_info itself fails, work through Steps 2–4 below.

Step 2 — `BASE_URL` checks

The BASE_URL env var must:

Include the scheme: https://graylog.example.com (or http:// for local).
Not end with /api or a trailing slash. The server adds the API path.
Be reachable from the host running the MCP server (not from the user's laptop, if those differ).

Verify reachability:

curl -fsS -o /dev/null -w "%{http_code}\n" "$BASE_URL/api/system" -u "$API_TOKEN:token" && echo OK

If curl returns 200, the URL and token both work; the MCP server itself is misconfigured. If curl fails, it is a network / auth problem.

Step 3 — `API_TOKEN` checks

Tokens are generated in the Graylog UI under Account → Edit profile → Create token.
Auth uses the token as the username and the literal string token as the password (Graylog convention). Confirm the MCP server's HTTP basic auth header reflects this.
Tokens can expire or be revoked. If curl returns 401 with a known-good URL, regenerate the token.

Step 4 — HTTP status → fix mapping

Status	Meaning	Fix
401	Token invalid / expired	Regenerate token, update `API_TOKEN`.
403	Token valid, lacks scope	Ask the Graylog admin to grant read access to the streams you need.
404 on stream filter	Stream ID doesn't exist or token can't see it	Call `list_streams` to confirm valid IDs visible to this token.
5xx	Graylog server-side issue	Not the MCP server's fault. Check Graylog itself.

Step 5 — Empty results when results are expected

If a search returns zero hits but you know logs exist:

Time zone. Graylog stores UTC. If you pass from/to as local-time ISO strings without a UTC offset, you may be querying the wrong window. Always use Z-suffixed UTC.
Query syntax. Elasticsearch query string, not pure Lucene. field=value won't work; use field:value. AND/OR must be uppercase.
Field casing. Field names are case-sensitive. service:foo ≠ Service:foo.
Stream filter mismatch. If you pass a streamId the token can't read, you get an empty (not an error) response.

Step 6 — `list_streams` returns empty

The token has no stream-read permissions. Ask the admin to grant read access; the MCP server itself is fine.

When to give up and ask

If steps 1–5 all check out and the tool still fails, the problem is on the Graylog server side (cluster issue, indexer down, retention purge). Surface what you've verified and ask the user to check with their Graylog operator or check the Graylog /api/system/cluster/health endpoint directly.

---name: troubleshootingdescription: Use when Graylog MCP tools return errors (connection refused, 401, target not found, empty results when results are expected). Diagnoses connectivity, auth, and configuration. Triggers on graylog tool failures, "connection refused", "401", "target not found", "graylog isn't returning anything".---# Graylog MCP — TroubleshootingUse this skill when Graylog MCP tool calls fail or return nothing unexpectedly.## Step 1 — Always start with `get_system_info`If any other tool fails, call `get_system_info` first. It tells you whether the server is reachable and the credentials are valid. If it returns successfully, the connection is fine and the issue is in the query.If `get_system_info` itself fails, work through Steps 2–4 below.## Step 2 — `BASE_URL` checksThe `BASE_URL` env var must:- Include the scheme: `https://graylog.example.com` (or `http://` for local).- Not end with `/api` or a trailing slash. The server adds the API path.- Be reachable from the host running the MCP server (not from the user's laptop, if those differ).Verify reachability:```bashcurl -fsS -o /dev/null -w "%{http_code}\n" "$BASE_URL/api/system" -u "$API_TOKEN:token" && echo OK```If `curl` returns 200, the URL and token both work; the MCP server itself is misconfigured. If `curl` fails, it is a network / auth problem.## Step 3 — `API_TOKEN` checks- Tokens are generated in the Graylog UI under **Account → Edit profile → Create token**.- Auth uses the token as the **username** and the literal string `token` as the **password** (Graylog convention). Confirm the MCP server's HTTP basic auth header reflects this.- Tokens can expire or be revoked. If `curl` returns 401 with a known-good URL, regenerate the token.## Step 4 — HTTP status → fix mapping| Status | Meaning | Fix ||---|---|---|| 401 | Token invalid / expired | Regenerate token, update `API_TOKEN`. || 403 | Token valid, lacks scope | Ask the Graylog admin to grant read access to the streams you need. || 404 on stream filter | Stream ID doesn't exist or token can't see it | Call `list_streams` to confirm valid IDs visible to this token. || 5xx | Graylog server-side issue | Not the MCP server's fault. Check Graylog itself. |## Step 5 — Empty results when results are expectedIf a search returns zero hits but you know logs exist:- **Time zone.** Graylog stores UTC. If you pass `from`/`to` as local-time ISO strings without a UTC offset, you may be querying the wrong window. Always use `Z`-suffixed UTC.- **Query syntax.** Elasticsearch query string, not pure Lucene. `field=value` won't work; use `field:value`. `AND`/`OR` must be uppercase.- **Field casing.** Field names are case-sensitive. `service:foo` ≠ `Service:foo`.- **Stream filter mismatch.** If you pass a `streamId` the token can't read, you get an empty (not an error) response.## Step 6 — `list_streams` returns emptyThe token has no stream-read permissions. Ask the admin to grant read access; the MCP server itself is fine.## When to give up and askIf steps 1–5 all check out and the tool still fails, the problem is on the Graylog server side (cluster issue, indexer down, retention purge). Surface what you've verified and ask the user to check with their Graylog operator or check the Graylog `/api/system/cluster/health` endpoint directly.

Frequently asked questions