Troubleshooting¶

Common issues and solutions when using FHIR Frog.

Server Connection Issues¶

Connection Refused¶

Problem:

Connection refused: http://localhost:8080/fhir

Solutions:

Check server is running:

curl http://localhost:8080/fhir/metadata

Verify URL:

@FhirServerUrl("http://localhost:8080/fhir")  // Correct
@FhirServerUrl("http://localhost:8080")       // Missing /fhir

Check Testcontainers:

@DynamicFhirServerUrl
static String getUrl() {
    return "http://localhost:" + fhirServer.getMappedPort(8080) + "/fhir";
}

Timeout¶

Problem:

Read timed out after 30000ms

Solutions:

Increase timeout:

FhirContext ctx = FhirContext.forR4();
ctx.getRestfulClientFactory().setSocketTimeout(60000);

Wait for server readiness:

@Container
static GenericContainer<?> server = new GenericContainer<>(...)
    .waitingFor(Wait.forHttp("/fhir/metadata")
        .withStartupTimeout(Duration.ofMinutes(2)));

TestScript Errors¶

Resource Not Found¶

Problem:

TestScript not found: classpath:fhir/test.json

Solutions:

Check file location:

src/test/resources/fhir/test.json  ✓
src/test/resources/test.json       ✗

Verify classpath prefix:

@TestScript("classpath:fhir/test.json")  // Correct
@TestScript("fhir/test.json")            // Missing classpath:

Invalid TestScript¶

Problem:

Invalid TestScript: Missing required field 'status'

Solution:

{
  "resourceType": "TestScript",
  "status": "draft",  // Required
  "name": "Test"      // Required
}

Variable Extraction Issues¶

Variable Not Found¶

Problem:

Variable 'patientId' not found

Solutions:

Extract before using:

* operation create Patient from patient as response
* variable patientId = Patient.id from response  // Extract first
* operation read Patient/${patientId}            // Then use

Check sourceId:

* variable patientId = Patient.id from createResponse  // Must match responseId

Empty Variable¶

Problem:

Variable 'patientId' is empty

Solutions:

Validate extraction:

* operation create Patient from patient as response
* assert expression = "Patient.id.exists()"  // Validate first
* variable patientId = Patient.id from response

Check FHIRPath:

# Correct
* variable id = Patient.id

# Wrong
* variable id = Patient.identifier  // Returns array, not string

Assertion Failures¶

Response Code Mismatch¶

Problem:

Expected: 201, Actual: 400

Solutions:

Check request body:

* operation create Patient from patient
* assert responseCode = 400  // If expecting error

Validate resource:

* operation validate Patient from patient
* assert expression = "OperationOutcome.issue.where(severity='error').empty()"

FHIRPath Errors¶

Problem:

FHIRPath evaluation failed: Unknown function 'contains'

Solutions:

Use correct syntax:

# Correct
* assert expression = "Patient.name.family = 'Smith'"

# Wrong
* assert expression = "Patient.name.family.contains('Smith')"  // Use matches()

Check resource type:

* assert resource = Patient  // Validates resource type first
* assert expression = "Patient.name.exists()"

Fixture Issues¶

Fixture Not Found¶

Problem:

Fixture 'patient' not found

Solutions:

Define fixture:

Fixture: patient from "patient.json"

Test: "Create patient"
  * operation create Patient from patient  // Now available

Check file path:

src/test/resources/fhir/patient.json  ✓
src/test/resources/patient.json       ✗

Invalid Fixture¶

Problem:

Invalid fixture: Not a valid FHIR resource

Solution:

{
  "resourceType": "Patient",  // Required
  "name": [{"family": "Smith"}]
}

TestPlan Issues¶

Circular Dependency¶

Problem:

Circular dependency detected: PlanA -> PlanB -> PlanA

Solution:

Restructure TestPlans to avoid cycles:

# Before (circular)
PlanA depends on PlanB
PlanB depends on PlanA

# After (hierarchical)
PlanA depends on PlanC
PlanB depends on PlanC

TestPlan Not Found¶

Problem:

TestPlan 'TestPlan/suite' not found

Solutions:

Check reference format:

@TestPlan("TestPlan/suite")  // Correct
@TestPlan("suite")            // Missing TestPlan/ prefix

Verify TestPlan exists:

curl http://localhost:8080/fhir/TestPlan/suite

Build Issues¶

Maven Plugin Not Found¶

Problem:

Plugin 'fhir-frog-maven-plugin' not found

Solution:

Add plugin repository:

<pluginRepositories>
    <pluginRepository>
        <id>gitlab</id>
        <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
    </pluginRepository>
</pluginRepositories>

Dependency Conflicts¶

Problem:

Conflicting HAPI FHIR versions

Solution:

Use dependency management:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>ca.uhn.hapi.fhir</groupId>
            <artifactId>hapi-fhir-bom</artifactId>
            <version>6.4.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Testcontainers Issues¶

Container Won't Start¶

Problem:

Container failed to start

Solutions:

Check Docker:
```
docker ps
docker info
```

Increase timeout:

@Container
static GenericContainer<?> server = new GenericContainer<>(...)
    .withStartupTimeout(Duration.ofMinutes(5));

Check logs:

System.out.println(fhirServer.getLogs());

Port Already in Use¶

Problem:

Port 8080 is already in use

Solution:

Use dynamic ports:

@Container
static GenericContainer<?> server = new GenericContainer<>(...)
    .withExposedPorts(8080);  // Docker assigns random host port

@DynamicFhirServerUrl
static String getUrl() {
    return "http://localhost:" + server.getMappedPort(8080) + "/fhir";
}

Performance Issues¶

Slow Tests¶

Solutions:

Reuse containers:

@Container
static GenericContainer<?> server = new GenericContainer<>(...)
    .withReuse(true);

Use persistent server:

./start-test-server.sh
mvn test -Dfhir.server.url=http://localhost:8080/fhir

Parallel execution:

<plugin>
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
        <parallel>classes</parallel>
        <threadCount>4</threadCount>
    </configuration>
</plugin>

Memory Issues¶

Problem:

OutOfMemoryError: Java heap space

Solutions:

Increase heap:
```
export MAVEN_OPTS="-Xmx2g"
mvn test
```
Limit test scope:
```
mvn test -Dtest=PatientTests
```

Getting Help¶

Debug Mode

Enable verbose logging to see detailed execution:

mvn test -X

Report Issues

Found a bug? Report it on GitLab Issues

Enable Debug Logging¶

<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>1.4.14</version>
    <scope>test</scope>
</dependency>

<!-- logback-test.xml -->
<configuration>
    <logger name="org.fhirfrog.frog" level="DEBUG"/>
    <logger name="ca.uhn.fhir" level="INFO"/>
</configuration>

Next Steps¶

Best Practices - Avoid common pitfalls
Examples - Working examples