What causes "collection not found" in badges/shields?

Verify the collection ID from the Workshop collection URL (id= query param) and that it is public

badges/shields · warning · NotFound

collection not found

Error message

collection not found

What it means

The Steam Workshop collection badge queries the Steam ISteamRemoteStorage/GetCollectionDetails API and validates with collectionFoundOrNotSchema. If `response.collectiondetails[0].result` is set (Steam returns a non-zero result code meaning the lookup failed), `handle` throws NotFound 'collection not found'.

Source

Thrown at services/steam/steam-workshop.service.js:147

  static version = '1'

  async handle({ collectionId }) {
    const options = {
      method: 'POST',
      form: {
        collectioncount: '1',
        'publishedfileids[0]': collectionId,
      },
    }

    const json = await this.fetch({
      schema: collectionFoundOrNotSchema,
      options,
    })

    if (json.response.collectiondetails[0].result) {
      throw new NotFound({ prettyMessage: 'collection not found' })
    }

    return this.constructor.render({
      size: json.response.collectiondetails[0].children.length,
    })
  }
}

class SteamFileService extends BaseSteamAPI {
  static interf = 'ISteamRemoteStorage'

  static method = 'GetPublishedFileDetails'

  static version = '1'

  async onRequest({ response }) {
    throw new Error(`onRequest() wasn't implemented for ${this.name}`)
  }

View on GitHub (pinned to 766fd8bc89)

Solutions

Verify the collection ID from the Workshop collection URL (id= query param) and that it is public
Confirm the id is a collection, not a single Workshop file (use the file badge for items)
Check the collection still exists and wasn't deleted or made friends-only
Re-test via the Steam Workshop page in an incognito browser; if it 404s there the badge will too

Example fix

// before
/badge/steam/collection/12345   // this is a single item id
// after
/badge/steam/collection/67890   // actual published collection id

Defensive patterns

Strategy: try-catch

Validate before calling

const res = await fetch(`https://steamcommunity.com/sharedfiles/filedetails/?id=${collectionId}`);
if (!res.ok || (await res.text()).includes('Error')) throw new Error('collection not publicly accessible');

Type guard

const isValidCollectionId = (id) => typeof id === 'string' && /^\d{6,}$/.test(id);

Try / catch

try {
  return await steamCollectionSize({ id: collectionId });
} catch (err) {
  if (err prettyMessage === 'collection not found') {
    // render 'collection unavailable' badge and verify the id on the Workshop
  } else throw err;
}

Prevention

Copy collection ids directly from the Workshop collection URL
Verify the id is a collection, not a single Workshop file
Re-check periodically that embedded collections remain public and undeleted

When it happens

Trigger: Calling /steam/collection with an `id` that is not a published Workshop collection, is private, has been deleted, or is a Workshop item of a different app whose collectiondetails come back with a failure result code.

Common situations: Copying an item ID (workshop file) instead of a collection ID; collection made private/removed after the badge was embedded; wrong appId/namespace so Steam can't resolve the ID.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of badges/shields@766fd8bc89 (2026-08-30). Data as JSON: /api/errors/0a126b49c728f9a6. Report an issue: GitHub.