Independent resource · Not affiliated with, endorsed by or operated by GS1® · Learn more
    Back to the resolver tester

    Common GS1 resolver errors and how to fix them

    These are the conformance problems that come up most when testing GS1 Digital Link resolvers. Each one shows what usually causes it and what to change.

    No default link found

    Usual cause: The linkset has no gs1:defaultLink, or it is written with a different namespace than the checker expects (for example https://gs1.org/voc/defaultLink instead of https://ref.gs1.org/voc/defaultLink).

    Fix: Give every identifier exactly one default link and use the ref.gs1.org vocabulary URIs as the link relation keys.

    No Link header pointing to the linkset

    Usual cause: The redirect response doesn't advertise where the full linkset lives.

    Fix: Add a header such as Link: <https://example.com/01/09506000164908?linkType=linkset>; rel="linkset"; type="application/linkset+json" to redirect responses.

    Link to JSON-LD context file not detected

    Usual cause: When serving the linkset, the response has no Link header to a JSON-LD context.

    Fix: Include a Link header with rel="http://www.w3.org/ns/json-ld#context" pointing to a JSON-LD context file.

    CORS headers missing

    Usual cause: Browsers block web apps from reading your resolver's answers.

    Fix: Return Access-Control-Allow-Origin: * (and answer OPTIONS preflight requests) on resolver responses.

    Wrong redirect status

    Usual cause: The resolver uses 301 or 302 for normal redirects.

    Fix: Use 307 Temporary Redirect so the destination can change later without browsers caching the old one.

    Unknown batch or serial returns 404

    Usual cause: The resolver only matches the exact full path.

    Fix: Walk up the tree: if /01/{gtin}/10/{batch} isn't known, answer with the GTIN-level links instead.

    Invalid identifiers aren't rejected

    Usual cause: A GTIN with a bad check digit or wrong length still gets redirected.

    Fix: Validate the syntax and check digit and return 400 Bad Request for invalid Digital Link URIs.

    Find out which ones affect you

    Run your Digital Link through the tester to see every check, the exact request sent and the response received. The authoritative rules are in the GS1-Conformant resolver standard.

    Test a resolver now →

    Related: What is GS1 Digital Link? · GS1 link types · Common resolver errors