Diagnosing Failed Environment Variable Substitution in Hoppscotch

When Variables Don't Resolve

You send a request in Hoppscotch and the response shows ${API_KEY} or {{baseUrl}} literally in the URL, header, or body instead of the expected value. The request fails with 401, 404, or a malformed URL error. This guide walks through the most common causes, a systematic diagnostic sequence, and the fix for each root cause.

Symptom-to-Cause Quick Reference

Ordered Diagnostic Checks

1. Confirm the Active Environment

Open the environment selector (top-right dropdown). Verify the environment containing your variable is selected — not \"No Environment\" or a different workspace environment. Hoppscotch only substitutes variables from the currently active environment plus globals.

2. Inspect Variable Definition

Click the environment name → \"Edit\" to open the environment manager. Check:

• Variable name matches exactly (case-sensitive) what you use in ${...}
• No extra spaces: API_KEY not API_KEY
• Value is set (not empty string)
• For nested objects, the full path exists: { \"user\": { \"id\": 123 } } supports ${env.user.id}

3. Verify Syntax in the Request

In the request builder, examine every field using the variable. Hoppscotch only recognizes ${VARIABLE_NAME}. Common mistakes:

• $VARIABLE_NAME (missing braces)
• {{VARIABLE_NAME}} (Postman/Insomnia syntax)
• ${variable_name} vs ${VARIABLE_NAME} (case mismatch)

4. Test with a Minimal Request

Create a new GET request to https://httpbin.org/get. Add a header X-Test: ${YOUR_VAR}. Send and open the request inspector (network tab or Hoppscotch's response panel). The resolved header should show your value, not the placeholder.

5. Check Browser Console for Runtime State

Open DevTools (F12) → Console. Run:

// Inspect Hoppscotch's internal environment store
console.log(window.hoppscotch?.env)

This reveals the merged environment (globals + active) as Hoppscotch sees it at runtime. Confirm your variable appears with the expected value.

6. Look for Pre-request Script Overwrites

If the variable works on first send but fails on subsequent sends, check the \"Pre-request Script\" tab of the request or collection. Scripts like:

pm.environment.set('API_KEY', '') // or any assignment

can clear or change the value before the next run. Hoppscotch's scripting API mirrors Postman's pm.* namespace.

7. Test Persistence Across Reloads

Reload the page. Re-select the environment. If variables disappear, the browser's localStorage may be blocked, full, or cleared by privacy extensions. Hoppscotch stores environments in localStorage under keys prefixed with hoppscotch_.

Fixes Mapped to Findings

Variable Missing from Active Environment

Fix: Add the variable in the environment editor (Environment → Edit → Add Variable). Use the exact name referenced in requests. Scope: choose \"Environment\" for per-env values, \"Global\" for shared values.

Syntax Mismatch

Fix: Replace every occurrence of $VAR, {{VAR}}, or %VAR% with ${VAR}. Do a project-wide search in the collection JSON (Export → open in editor → search for \\$\\{ pattern).

Unescaped Characters Breaking Requests

Fix: Encode values at definition time or use pre-request scripts. Example: if redirect_url contains ?foo=bar&baz=qux, the ampersand breaks query parsing. Store the encoded form:

// In pre-request script or environment value
pm.environment.set('redirect_url', encodeURIComponent('https://example.com/cb?foo=bar&baz=qux'))

Then use ${redirect_url} directly. Risk: Double-encoding if the value is already encoded. Verify with console.log(decodeURIComponent(pm.environment.get('redirect_url'))).

Environment Not Persisting

Fix: Check browser settings: Settings → Privacy → Site Data → allow localStorage for the Hoppscotch origin. Disable extensions that clear storage on close (e.g., \"Click&Clean\", some ad blockers). If localStorage is unavailable, export environments as JSON (Environment → Export) and re-import after each session.

Variable Overwritten by Script

Fix: Remove or guard the assignment. Pattern:

// Only set if not already defined
if (!pm.environment.get('API_KEY')) {
  pm.environment.set('API_KEY', 'fallback-value');
}

Or move the logic to a collection-level pre-request script that runs once per session.

Built-in Placeholder Conflict

Fix: Rename your variable. Hoppscotch reserves: $uuid, $timestamp, $isoTimestamp, $randomInt, $randomFloat. Prefix custom vars: MY_UUID, APP_TIMESTAMP.

Nested Path Failure

Fix: Ensure the source object exists and use correct dot notation. In environment JSON:

{
  \"env\": {
    \"user\": { \"id\": 42, \"role\": \"admin\" },
    \"api\": { \"baseUrl\": \"https://api.example.com\" }
  }
}

Then ${env.user.id} and ${env.api.baseUrl} resolve. If env.user is undefined, the whole chain fails silently.

Escalation Criteria

Escalate to Hoppscotch GitHub issues or community Discord when:

• Variables resolve in console (window.hoppscotch.env) but not in sent requests — indicates a substitution engine bug.
• Environment import/export produces malformed JSON that breaks on re-import.
• Pre-request scripts throw \"pm is not defined\" in the console — scripting runtime not initialized.
• Variables persist in localStorage but disappear after browser restart despite allowed storage — possible quota or corruption issue.

Before reporting, include: Hoppscotch version (Settings → About), browser/OS, exported environment JSON (redact secrets), and steps to reproduce from a clean profile.

Verification Checklist

1. Active environment matches the one containing the variable.
2. Variable name in request uses ${EXACT_NAME}.
3. Value appears in window.hoppscotch.env console output.
4. Minimal test request to httpbin.org shows resolved header/param.
5. No pre-request script clears the variable before use.
6. Page reload retains the environment (localStorage functional).

Limitations

This guide covers the web app (app.hoppscotch.io or self-hosted). The CLI and desktop wrapper may have different persistence layers. Hoppscotch does not support conditional variable logic (if/else) in environment files — use pre-request scripts for dynamic values. Nested arrays (e.g., ${env.servers[0].url}) are not officially documented; treat as unsupported.

Quick Self-Test

Create a throwaway environment named \"diag-test\" with one variable: TEST_VAL = \"hello-world\". Make a request to https://httpbin.org/headers with header X-Diag: ${TEST_VAL}. Send. In the response JSON, find \"X-Diag\": \"hello-world\". If present, substitution works end-to-end. If the header shows ${TEST_VAL}, re-run the diagnostic checks above.