mongodb/node-mongodb-native · error · MongoRuntimeError

File with id ${id} not found

Error message

File with id ${id} not found

What it means

Thrown by GridFSBucket.rename() when updateOne against the files collection matched zero documents (matchedCount === 0). It is a MongoRuntimeError indicating the target file does not exist, so its filename cannot be changed. No documents are modified when this fires. Distinct from the delete() variant (error 260) only by message and method.

Source

Thrown at src/gridfs/index.ts:237

      this.s._filesCollection,
      this.s.options.readPreference,
      { filename },
      { timeoutMS: this.s.options.timeoutMS, ...options, sort, skip }
    );
  }

  /**
   * Renames the file with the given _id to the given string
   *
   * @param id - the id of the file to rename
   * @param filename - new name for the file
   */
  async rename(id: ObjectId, filename: string, options?: { timeoutMS: number }): Promise<void> {
    const filter = { _id: id };
    const update = { $set: { filename } };
    const { matchedCount } = await this.s._filesCollection.updateOne(filter, update, options);
    if (matchedCount === 0) {
      throw new MongoRuntimeError(`File with id ${id} not found`);
    }
  }

  /** Removes this bucket's files collection, followed by its chunks collection. */
  async drop(options?: { timeoutMS: number }): Promise<void> {
    const { timeoutMS } = resolveOptions(this.s.db, options);
    let timeoutContext: CSOTTimeoutContext | undefined = undefined;

    if (timeoutMS) {
      timeoutContext = new CSOTTimeoutContext({
        timeoutMS,
        serverSelectionTimeoutMS: this.s.db.client.s.options.serverSelectionTimeoutMS
      });
    }

    if (timeoutContext) {
      await this.s._filesCollection.drop({ timeoutMS: timeoutContext.remainingTimeMS });
      const remainingTimeMS = timeoutContext.getRemainingTimeMSOrThrow(

View on GitHub (pinned to 3366c21a63)

Solutions

1. Look up the file first: const f = await bucket.find({ _id: id }, { limit: 1 }).next(); if (f) await bucket.rename(id, newName);
2. Make sure id is an ObjectId and that the GridFSBucket uses the matching db/bucketName.
3. If rename is best-effort, catch MongoRuntimeError and swallow the missing-file case.

Example fix

// before
await bucket.rename(id, 'renamed.bin');

// after
const file = await bucket.find({ _id: id }, { limit: 1 }).next();
if (file) await bucket.rename(id, 'renamed.bin');

async function safeRename(bucket, id, name) {
  const exists = await bucket.find({ _id: id }, { limit: 1 }).hasNext();
  if (exists) await bucket.rename(id, name);
}

function isObjectId(v): v is ObjectId { return v instanceof ObjectId; }

try {
  await bucket.rename(id, name);
} catch (e) {
  if (e instanceof MongoRuntimeError && /not found/.test(e.message)) return;
  throw e;
}

When it happens

Trigger: Calling bucket.rename(id, newName) with an id not present in the bucket's files collection. Reusing an id after deletion, pointing at the wrong bucket/database, or passing a non-ObjectId value.

Common situations: Renaming already-deleted files; multi-tenant systems where the id came from another tenant's bucket; passing the filename as the first arg instead of the _id.

Related errors

• File not found for id ${id}
• Options cannot be changed after the stream is initialized
• Stream start (${options.start}) must not be more than the le
• Stream start (${options.start}) must not be negative
• Stream start (${options.start}) must not be greater than str

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/d739afee1ad0cd2c.json. Report an issue: GitHub.