perspective-dev/perspective · error · TypeError

TileSourceSpec must be an object

Error message

TileSourceSpec must be an object

What it means

parseTileSourceSpec is a validation/normalization gate for untrusted tile source input (JSON entries or registerTileSource arguments). This generic guard fires when the input is not a non-null object — e.g. a raw string, number, array element misplaced, or null — so field validation cannot proceed. A TypeError naming the offending spec is expected behavior of this validator.

Solutions

1. Pass an object with id/label/template/attribution fields instead of a scalar or null
2. Check JSON parsing: the value may have been double-unwrapped or defaulted to null
3. Wrap registerTileSource calls in try/catch to surface the misconfigured spec to the caller

When it happens

Trigger: Thrown at packages/viewer-charts/src/ts/map/tile-source.ts:131 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of perspective-dev/perspective@11c8238c0c (2026-09-09). Data as JSON: /api/errors/2b84c90d5e7670d7. Report an issue: GitHub.

Appendix: source

Thrown at packages/viewer-charts/src/ts/map/tile-source.ts:131

    /** See {@link TileSource.attribution}. */
    readonly attribution: string;

    /** See {@link TileSource.tileSize}. Default 256. */
    readonly tile_size: number;

    /** See {@link TileSource.maxZoom}. Default 19. */
    readonly max_zoom: number;
}

/**
 * Validate + normalize an untrusted spec (a JSON entry or a
 * `registerTileSource` argument). Throws `TypeError` naming the
 * offending field; returns a frozen spec with defaults applied.
 */
export function parseTileSourceSpec(input: unknown): TileSourceSpec {
    if (typeof input !== "object" || input === null) {
        throw new TypeError("TileSourceSpec must be an object");
    }

    const raw = input as Record<string, unknown>;
    const str = (key: string): string => {
        const v = raw[key];
        if (typeof v !== "string" || v.length === 0) {
            throw new TypeError(
                `TileSourceSpec.${key} must be a non-empty string`,
            );
        }

        return v;
    };

    const id = str("id");
    const label = str("label");
    const template = str("template");
    const attribution = str("attribution");

View on GitHub (pinned to 11c8238c0c)