Troubleshooting

Variable Interpolation

Variables not being replaced

1. Check your environment file — Variables must be defined in a .env or hitspec.yaml file.
2. Verify the environment is active — Use hitspec run --env production (or HITSPEC_ENV), or press ctrl+e in hitspec studio.
3. Check for typos — Variable names are case-sensitive. {{baseUrl}} and {{baseURL}} are different.

### Correct: baseUrl is defined in the active environment
GET {{baseUrl}}/users

### Wrong: base_url is not the same variable as baseUrl
GET {{base_url}}/users

Circular variable references

# hitspec.yaml — this will cause a circular reference warning
environments:
  dev:
    a: "{{b}}"
    b: "{{a}}"

Captures & Dependencies

Capture value is empty

1. Verify the path — Use name from body.data.id and ensure the response actually contains that path.
2. Check response content type — Body paths only work on JSON responses.
3. Ensure the request succeeds — If the request returns an error status, the response body may not contain the expected structure.

### Login
# @name login

POST {{baseUrl}}/auth/login
Content-Type: application/json

{"email": "test@example.com", "password": "secret"}

>>>capture
token from body.accessToken
<<<

Dependency order issues

### Login (must come first)
# @name login

POST {{baseUrl}}/auth/login
Content-Type: application/json

{"email": "admin@test.com", "password": "pass"}

>>>capture
token from body.token
<<<

### Use the token (depends on Login)
# @depends login

GET {{baseUrl}}/profile
Authorization: Bearer {{login.token}}

SSL / TLS Errors

Certificate verification failed

# Option 1: Disable SSL verification for testing
hitspec run --insecure tests.http   # or the short form: -k

# Option 2: Set in hitspec.yaml
# validateSSL: false

Self-signed certificates

Timeout Issues

Request timeout

# Increase timeout (default is 30s)
hitspec run --timeout 60s tests.http

timeout: 60000  # milliseconds

Stress test timeout

hitspec run api.http --stress --duration 60s --rate 100 --timeout 10s

hitspec serve & studio Issues

Port already in use

# Use a different port
hitspec serve --api-only --port 8080

# Or find and kill the process using port 4000
lsof -ti:4000 | xargs kill

The API server rejects my request

Files not appearing in the file list

1. Check the working directory — hitspec studio uses the current directory by default.
2. Check file extensions — Only .http and .hitspec files are shown.
3. Nested directories — Files in subdirectories are shown in a tree structure. Expand the folder.

Assertion Failures

Unexpected assertion results

### Get user
GET {{baseUrl}}/users/1

>>>
expect status 200

# Wrong: compares the whole body to a string, which is almost never what you want
# expect body == "John"

# Correct: address the JSON field with body.<path>
expect body.name == "John"
expect body.roles[0] == "admin"
<<<

Schema validation failures

1. Check the schema path — Relative paths are resolved from the file’s directory.
2. Validate your schema — Ensure it’s valid JSON Schema (draft-07).
3. Check for required fields — The response must include all required fields.

CI/CD Issues

Exit codes

GitHub Actions fails but works locally

1. Environment variables — Make sure all required variables are set in your CI environment.
2. Network access — Ensure the CI runner can reach your API endpoints.
3. Timeouts — CI runners may be slower; increase timeouts.

- name: Run API tests
  run: hitspec run --timeout 60s --env ci tests/
  env:
    BASE_URL: ${{ vars.API_URL }}

Performance

Slow test execution

1. Enable parallel execution — hitspec run --parallel tests/
2. Reduce timeout for fast-failing — hitspec run --timeout 5s
3. Use @if/@unless to skip irrelevant tests conditionally.

Large response bodies

### List items
GET {{baseUrl}}/items

>>>
# Slow: compares the entire body
# expect body == "..."

# Fast: only checks the field you care about
expect body.data[0].id exists
<<<

Getting Help

1. Run with --verbose for detailed output.
2. Check the GitHub Issues for known bugs.
3. Open a new issue with your .http file content, error message, and hitspec version (hitspec --version).