immich-app/immich · error · BadRequestException

Invalid job name

Error message

Invalid job name: ${name}

What it means

The legacy `start` switch only maps known QueueName values to concrete jobs; any queue name falling through to `default` throws this. It means the caller supplied a name that is not a runnable job target in this code path.

Solutions

1. Use only the queue names the legacy start path supports (video conversion, thumbnail generation, library scan, etc.)
2. Update client scripts to the queue names of the deployed server version
3. For concurrent queues use the queue update/resume endpoints instead of job start
4. Log and inspect the `name` value to catch typos

Example fix

// before
await api.runJob('backgroundTask' as any); // Invalid job name
// after
await api.runJob('videoConversion'); // a supported job name

const STARTABLE: QueueName[] = ['videoConversion','thumbnailGeneration','libraryScan','libraryDelete','migration','generateMemories','backupDatabase'];
if (!STARTABLE.includes(name)) throw new InvalidJobName(name);

function isStartableQueue(name: string): name is QueueName {
  return ['videoConversion','thumbnailGeneration','libraryScan','libraryDelete','migration','generateMemories','backupDatabase'].includes(name);
}

try {
  await queueService.start(auth, name, dto);
} catch (e) {
  if (e instanceof BadRequestException && e.message.startsWith('Invalid job name')) {
    logger.error(`Unsupported job: ${name}`);
    return;
  }
  throw e;
}

When it happens

Trigger: Calling runCommandLegacy/start with a queue name outside the handled cases (e.g. BackgroundTask, Threading-style concurrent queues, or a misspelled/renamed queue name).

Common situations: Version drift: client hardcoded a queue name removed/renamed in a newer server; automation scripts enumerating all QueueName values and trying to start every one; typos in admin tooling.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Invalid ack type
• Invalid targetSize: ' + targetSize
• Job is already running
• Skipping thumbnail generation for asset
• Task with id not found

AI-assisted analysis of immich-app/immich@e55ac299a4 (2026-09-15). Data as JSON: /api/errors/c03fdb9d2e44d703. Report an issue: GitHub.

Appendix: source

Thrown at server/src/services/queue.service.ts:249

      case QueueName.FacialRecognition: {
        return this.jobRepository.queue({ name: JobName.FacialRecognitionQueueAll, data: { force } });
      }

      case QueueName.Library: {
        return this.jobRepository.queue({ name: JobName.LibraryScanQueueAll, data: { force } });
      }

      case QueueName.BackupDatabase: {
        return this.jobRepository.queue({ name: JobName.DatabaseBackup, data: { force } });
      }

      case QueueName.Ocr: {
        return this.jobRepository.queue({ name: JobName.OcrQueueAll, data: { force } });
      }

      default: {
        throw new BadRequestException(`Invalid job name: ${name}`);
      }
    }
  }

  private isConcurrentQueue(name: QueueName): name is ConcurrentQueueName {
    return ![
      QueueName.FacialRecognition,
      QueueName.StorageTemplateMigration,
      QueueName.DuplicateDetection,
      QueueName.BackupDatabase,
    ].includes(name);
  }

  async handleNightlyJobs() {
    const config = await this.getConfig({ withCache: false });
    const jobs: JobItem[] = [];

    if (config.nightlyTasks.databaseCleanup) {

View on GitHub (pinned to e55ac299a4)