wavetermdev/waveterm · error

missing zone file info for ${zoneId}:${fileName}

Error message

missing zone file info for ${zoneId}:${fileName}

What it means

fetchWaveFile reads a wave file's bytes and metadata from the backend over HTTP; the server is expected to return the file's WaveFileInfo as a base64-encoded JSON blob in the X-ZoneFileInfo response header. This error is thrown when a successful (non-204) response arrives without that header, meaning the backend did not supply the metadata the client requires to construct the file entry. It indicates a server-side response inconsistency or a stale/unresolvable zone-file reference.

Source

Thrown at frontend/app/store/global.ts:471

    const usp = new URLSearchParams();
    usp.set("zoneid", zoneId);
    usp.set("name", fileName);
    if (offset != null) {
        usp.set("offset", offset.toString());
    }
    const resp = await fetch(getWebServerEndpoint() + "/wave/file?" + usp.toString());
    if (!resp.ok) {
        if (resp.status === 404) {
            return { data: null, fileInfo: null };
        }
        throw new Error("error getting wave file: " + resp.statusText);
    }
    if (resp.status == 204) {
        return { data: null, fileInfo: null };
    }
    const fileInfo64 = resp.headers.get("X-ZoneFileInfo");
    if (fileInfo64 == null) {
        throw new Error(`missing zone file info for ${zoneId}:${fileName}`);
    }
    const fileInfo = JSON.parse(base64ToString(fileInfo64));
    const data = await resp.arrayBuffer();
    return { data: new Uint8Array(data), fileInfo };
}

function setNodeFocus(nodeId: string) {
    const layoutModel = getLayoutModelForStaticTab();
    layoutModel.focusNode(nodeId);
}

const objectIdWeakMap = new WeakMap();
let objectIdCounter = 0;
function getObjectId(obj: any): number {
    if (!objectIdWeakMap.has(obj)) {
        objectIdWeakMap.set(obj, objectIdCounter++);
    }
    return objectIdWeakMap.get(obj);

View on GitHub (pinned to a4447c1563)

Solutions

1. Check the raw response in devtools/network tab to confirm X-ZoneFileInfo is actually absent vs. unreadable
2. Verify the wave backend serving the request is up-to-date and running the same version as the frontend
3. Ensure no proxy/middleware strips X-ZoneFileInfo; add it to any header allowlist
4. Re-check zoneId/fileName spelling; force a refresh of the file listing cache
5. If the file is gone, handle it: re-fetch the zone file listing and remove stale references

Example fix

// before
const fileInfo64 = resp.headers.get("X-ZoneFileInfo");
if (fileInfo64 == null) {
    throw new Error(`missing zone file info for ${zoneId}:${fileName}`);
}
// after
const fileInfo64 = resp.headers.get("X-ZoneFileInfo");
if (fileInfo64 == null) {
    console.warn(`missing zone file info for ${zoneId}:${fileName}, refreshing zone listing`);
    await refreshZoneFileListing(zoneId);
    return { data: null, fileInfo: null };
}

const resp = await fetch(url);
const hasInfo = resp.ok && resp.status !== 204 && resp.headers.has("X-ZoneFileInfo");
if (!hasInfo) {
    await refreshZoneFileListing(zoneId);
    return null;
}

function hasZoneFileInfo(resp: Response): boolean {
    return resp.ok && resp.status !== 204 && resp.headers.get("X-ZoneFileInfo") != null;
}

try {
    const { data, fileInfo } = await fetchWaveFile(zoneId, fileName);
    // use data/fileInfo
} catch (e) {
    if (String(e).includes("missing zone file info")) {
        // treat file as unavailable: purge cache entry, refresh listing, or show placeholder
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling fetchWaveFile(zoneId, fileName) where the backend returns 200 but omits the X-ZoneFileInfo header — e.g. the zone/file exists in the routed route context but the zone file metadata is missing on disk, a proxy stripped the custom header, or hitting a stale web server build that predates the header.

Common situations: Reverse proxy or CSP middleware filtering non-standard X-* headers; mixed-version deployment where an old backend serves a new frontend; file was deleted from the zone dir between listing and fetch; pointing the frontend at the wrong endpoint via VITE/Wave server config.

Related errors

• call ${methodName} failed: ${resp.status} ${resp.statusText}
• failed to copy from file: %v
• no window found with workspace ${data.workspaceid}
• cannot call ${methodName}: no web endpoint
• call ${methodName} error: ${respData.error}

AI-assisted analysis of wavetermdev/waveterm@a4447c1563 (2026-09-01). Data as JSON: /api/errors/469787734f8bd489. Report an issue: GitHub.