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 select it in the UI.
3. Check for typos — Variable names are case-sensitive. {{baseUrl}} and {{baseURL}} are different.

# Correct — variable defined in environment
GET {{baseUrl}}/users

# Wrong — double-check the variable name matches your env file
GET {{base_url}}/users

​

Circular variable references

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

​

Captures & Dependencies

​

Capture value is empty

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

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

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

@capture token <- jsonpath $.accessToken

​

Dependency order issues

### Login (must come first)
POST {{baseUrl}}/auth/login
Content-Type: application/json

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

@capture token <- jsonpath $.token

###

### Use the token (depends on Login)
GET {{baseUrl}}/profile
Authorization: Bearer {{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

stress:
  profiles:
    heavy:
      duration: 60s
      rate: 100
      timeout: 10000

​

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

​

WebSocket disconnects

1. Check if the server is still running in your terminal.
2. Check for proxy/firewall — Some corporate proxies block WebSocket connections.
3. The client auto-reconnects with exponential backoff (1s to 30s). Wait a moment.

​

Files not appearing in sidebar

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 {{baseUrl}}/users/1

# Wrong — comparing string to number
@assert status == "200"

# Correct — status is a number
@assert status == 200

# Wrong — body is the raw string, use jsonpath for JSON
@assert body == {"name": "John"}

# Correct — use jsonpath to extract values
@assert jsonpath $.name == "John"

​

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 60000 --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 5000
3. Use @if/@unless to skip irrelevant tests conditionally.

​

Large response bodies

# Slow — validates entire body
@assert body != ""

# Fast — only checks the field you care about
@assert jsonpath $.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).