Troubleshooting¶

This page maps common FHIR Frog error codes to their causes and fixes.

Error codes¶

Code	Meaning	Fix
`missing_argument`	Required argument was not provided	Supply the missing argument; check tool documentation
`invalid_argument`	Argument value is invalid type or range	Check argument format and valid values
`argument_conflict`	Two conflicting arguments supplied (e.g., both `scriptPath` and `testPackage`)	Supply only one of the conflicting arguments
`io_error`	File or network I/O failed	Check file path, permissions, network connectivity
`parse_error`	Syntax error in input (TSH, JSON, YAML)	Check syntax at the reported line and column
`not_found`	Resource not found (file, package, server, profile)	Verify name/id; list available with `frog_*_list`
`name_conflict`	Resource name already exists	Use a different name, or confirm overwrite with `confirm=true`
`path_outside_workspace`	Path escapes the workspace directory	Use paths relative to `FROG_WORKSPACE`
`needs_confirmation`	Destructive operation requires confirmation	Add `confirm=true` to the tool call
`docker_unavailable`	Docker daemon not running or not accessible	Start Docker; check socket permissions and `DOCKER_HOST`
`network_error`	frog-runner is down or URL is wrong	Start with `frog_runner_start_local`; check `$FROG_RUNNER_URL` and port
`package_not_found`	FHIR package not in local cache	Install with `frog_package_install`
`timeout`	Operation exceeded time limit	Increase timeout; check server logs

Common issues¶

TSH syntax errors¶

Error: parse error at line 5, column 10

Cause: Typo in TSH keyword, wrong indentation, or missing * prefix.

Fix: 1. Check the error location 2. Verify keywords (case-sensitive): operation, assert, variable, Fixture:, Test:, etc. 3. Actions must be indented with * at the start of the line 4. Use frog_tsh_validate first to see all errors before compiling

Example:

// Wrong
Test: "My test"
  operation read Patient/123

// Right
Test: "My test"
  * operation read Patient/123

Search with parameters (TSH limitation)¶

Error: HAPI-1684: Unknown resource name 'Patient?family=Smith'

Cause: TSH cannot encode search parameters. The whole string becomes the resource name and the server rejects it.

Fix: Use JSON TestScript instead with "params": "?family=Smith", or write a bare search:

* operation search Patient as search_resp

For large filter-heavy tests, switch to JSON.

Read by ID fails with HTTP 400¶

Error: HTTP 400 Bad Request (no server log entry)

Cause: The engine rejects the path client-side when the id is in the resource field (e.g., read Patient/123).

Fix: Put the id in params instead:

{
  "operation": {
    "type": { "code": "read" },
    "resource": "Patient",
    "params": "/123",
    "encodeRequestUrl": true
  }
}

Use JSON TestScript; TSH does not support this syntax.

Variable substitution in URLs does not work¶

Error: Illegal character in path: ${patientId}

Cause: The engine does not substitute ${variableName} in operation URLs.

Fix: Use variables only in assertions or later variable definitions. For request parameterization, use JSON TestScript with known-literal values or restructure the test.

Docker is not running¶

Error: docker_unavailable, "Docker daemon 127.0.0.1:2375: connection refused"

Cause: Docker daemon is not running or the socket is not accessible.

Fix: - Linux: systemctl start docker or sudo systemctl start docker - macOS: Open Docker Desktop application - Windows: Open Docker Desktop from Start menu - Check permissions: sudo usermod -aG docker $USER (Linux)

Registry credentials are stale¶

Error: docker pull fails with "unauthorized"

Cause: A leftover docker login registry.gitlab.com from an old session is now invalid.

Fix:

docker logout registry.gitlab.com

Subsequent pulls will be anonymous (works for public images).

Runner is not responding¶

Error: network_error, "http://127.0.0.1:8080: connection refused"

Cause: Runner container is not running, port is wrong, or network is misconfigured.

Fix: 1. Start the runner: frog_runner_start_local(confirm: true) 2. Check the port: echo $FROG_RUNNER_PORT or check runner URL in frog_doctor 3. Check container status: docker ps | grep frog-runner

Test package not found¶

Error: package_not_found, "fhirfrog.au-core-tests#0.1.0 not found"

Cause: The package is not in the local cache (~/.fhir/packages).

Fix:

# List available packages
frog_package_list(includeRunner: true)

# Install a missing package
frog_package_install(
  packageId: "fhirfrog.au-core-tests",
  version: "0.1.0",
  confirm: true
)

Profile validation fails: "could not be found"¶

Error: Validate profile: http://example.org/Profile/MyPatient — resource does not conform: could not be found

Cause: The server does not have the profile loaded (the IG is not on the server).

Fix: 1. Load the IG on the server: the stock HAPI FHIR server (frog_server_start_local) starts without any IG preloaded. To get an IG-aware server, either use a server that already has the IG loaded, or pass an IG-aware image to frog_server_start_local(image: "...", confirm: true). 2. Or remove the validateProfile assertion if the profile is not available on the server 3. Or provide a --terminology-server when running tests

Create fails with HTTP 400¶

Error: Failed to create: HTTP 400

Cause: The fixture file has invalid FHIR JSON or a required field is missing.

Fix: 1. Check the fixture file is valid FHIR JSON (use fhir-cli.jar -validate if available) 2. Verify required fields for the resource type (e.g., Patient requires at least one identifier or name) 3. Check server logs: docker logs frog-sut (if using local server) 4. Manually test the create: curl -X POST http://127.0.0.1:8081/fhir/Patient -H "Content-Type: application/fhir+json" -d @patient.json

Assertion fails: "Expected 200 but got 404"¶

Error: Expected responseCode = 200 but got 404

Cause: The server does not have the requested resource (missing precondition, wrong URL, resource deleted).

Fix: 1. Verify the precondition resource was created in Setup: check TestReport for Setup phase results 2. Verify the search/read operation uses the correct resource type and parameters 3. Ensure the server is not empty: run a separate search test to verify data exists 4. Check server logs for details

Fixture file not found¶

Error: io_error, "Fixture file patient.json not found"

Cause: The path to the fixture is wrong or the file does not exist.

Fix: 1. Verify the file exists: ls fixtures/patient.json 2. Check the fixture reference in the TestScript matches the file name (case-sensitive) 3. Verify --fixtures or fixturesPath parameter points to the right directory 4. Use frog_check_ig to find the workspace root and correct paths

FROG_WORKSPACE not set¶

Error: path_outside_workspace, "FROG_WORKSPACE not configured"

Cause: The MCP does not know your workspace path.

Fix: Set FROG_WORKSPACE in the MCP client config or environment:

export FROG_WORKSPACE="/absolute/path/to/workspace"

Or in Claude Desktop / Kiro config:

{
  "env": {
    "FROG_WORKSPACE": "/absolute/path/to/workspace"
  }
}

HAPI server does not start¶

Error: timeout, "Server did not start within 60 seconds"

Cause: HAPI takes longer than expected or failed to start.

Fix: 1. Check container logs: docker logs frog-sut 2. Increase Docker memory (at least 2 GB) 3. Retry: frog_server_stop(confirm: true) then frog_server_start_local(confirm: true) 4. Check port is not in use: lsof -i :8081 (Linux/macOS)

Out of memory¶

Error: timeout or container killed/restarted

Cause: Docker ran out of memory for the SUT + runner.

Fix: 1. Stop containers: frog_server_stop(confirm: true) and frog_runner_stop(confirm: true) 2. Increase Docker memory: - macOS: Docker Desktop → Preferences → Resources → Memory (4–6 GB recommended) - Linux: Check docker system info | grep Memory 3. Retry

Getting more help¶

For issues not covered here:

Run frog_doctor to diagnose your environment
Check tool error details: tools return error.hint with fix suggestions
See the full troubleshooting reference: skill/fhir-frog/references/troubleshooting.md
Report the issue with: error code, tool name, command line/parameters, and output