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

Copy the id directly from the item's Workshop URL (?id=NNNN) to avoid transcription errors

badges/shields · warning · NotFound

file not found

Error message

file not found

What it means

The Steam Workshop file size badge calls GetPublishedFileDetails and validates with fileFoundOrNotSchema. A truthy `response.publishedfiledetails[0].result` indicates Steam could not resolve the published file, so `handle` throws NotFound 'file not found'.

Source

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

  static version = '1'

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

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

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

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

    return this.onRequest({ response: json.response.publishedfiledetails[0] })
  }
}

class SteamFileSize extends SteamFileService {
  static category = 'size'

  static route = {
    base: 'steam/size',
    pattern: ':fileId',
  }

  static openApi = {
    '/steam/size/{fileId}': {
      get: {
        summary: 'Steam File Size',

View on GitHub (pinned to 766fd8bc89)

Solutions

Copy the id directly from the item's Workshop URL (?id=NNNN) to avoid transcription errors
Confirm the item is publicly visible on the Workshop in an incognito session
Ensure the correct game/app path segment matches the item's app
If recently deleted/re-uploaded, use the new item's id

Example fix

// before
/badge/steam/workshop/size/1234
// after (full Workshop file id)
/badge/steam/workshop/size/2512345678

Defensive patterns

Strategy: try-catch

Validate before calling

const res = await fetch(`https://steamcommunity.com/sharedfiles/filedetails/?id=${fileId}`);
if (!res.ok) throw new Error(`workshop item ${fileId} not publicly visible`);

Type guard

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

Try / catch

try {
  return await steamWorkshopSize({ id: fileId });
} catch (err) {
  if (err prettyMessage === 'file not found') {
    // render 'item not found' badge; prompt maintainer to update the id
  } else throw err;
}

Prevention

Use the full numeric id from the item's Workshop URL (?id=NNNN), no truncation
Confirm the item is public in an incognito browser before embedding
Keep the game/app segment consistent with the item's app

When it happens

Trigger: Calling /steam/workshop/size (or related file badges) with a Workshop file `id` that was deleted, is private, doesn't exist, or belongs to a different game than the one in the URL.

Common situations: Typo or truncation of the long Workshop item ID; item hidden by the author or removed by moderators; embedding badges for items on private servers/mods.

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/26e3c3531fd5175b. Report an issue: GitHub.