{"record":{"id":"d4ce315f88b1bcf1","repo":"google-gemini/gemini-cli","slug":"loaded-metadata-for-task-taskid-is-missing-inte","errorCode":null,"errorMessage":"Loaded metadata for task ${taskId} is missing internal persisted state.","messagePattern":"Loaded metadata for task (.+?) is missing internal persisted state\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/a2a-server/src/persistence/gcs.ts","lineNumber":255,"sourceCode":"\n    try {\n      const metadataFile = this.storage\n        .bucket(this.bucketName)\n        .file(metadataObjectPath);\n      const [metadataExists] = await metadataFile.exists();\n      if (!metadataExists) {\n        logger.info(`Task ${taskId} metadata not found in GCS.`);\n        return undefined;\n      }\n      const [compressedMetadata] = await metadataFile.download();\n      const jsonData = gunzipSync(compressedMetadata).toString();\n      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment\n      const loadedMetadata = JSON.parse(jsonData);\n      logger.info(`Task ${taskId} metadata loaded from GCS.`);\n\n      const persistedState = getPersistedState(loadedMetadata);\n      if (!persistedState) {\n        throw new Error(\n          `Loaded metadata for task ${taskId} is missing internal persisted state.`,\n        );\n      }\n      const agentSettings = persistedState._agentSettings;\n\n      const workDir = await setTargetDir(agentSettings);\n      await fse.ensureDir(workDir);\n      const workspaceFile = this.storage\n        .bucket(this.bucketName)\n        .file(workspaceObjectPath);\n      const [workspaceExists] = await workspaceFile.exists();\n      if (workspaceExists) {\n        const tmpArchiveFile = join(tmpdir(), getTmpArchiveFilename(taskId));\n        try {\n          await workspaceFile.download({ destination: tmpArchiveFile });\n          await tar.x({ file: tmpArchiveFile, cwd: workDir });\n          logger.info(\n            `Task ${taskId} workspace restored from GCS to ${workDir}`,","sourceCodeStart":237,"sourceCodeEnd":273,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/packages/a2a-server/src/persistence/gcs.ts#L237-L273","documentation":"During GCSTaskStore.load(), after downloading and JSON-parsing the metadata blob from GCS, getPersistedState() is called to extract __persistedState. If the key is absent or its contents fail the isPersistedStateMetadata() structural check, the loaded data cannot be reconstructed into a runnable task and this error is thrown.","triggerScenarios":"Loading a task whose metadata was saved by an older code version (before __persistedState existed), manually edited in the GCS bucket, or corrupted during the gzip/JSON round-trip. Also fires if the metadata object is structurally valid JSON but missing the required _agentSettings or _taskState nested fields.","commonSituations":"Version mismatch between the code that saved the task and the code loading it; manual editing of GCS objects; schema migration gap; data corruption from interrupted writes.","solutions":["Re-save the task using the current code version to populate __persistedState.","If the task is obsolete, delete the GCS objects (tasks/<id>/metadata.tar.gz) and recreate the task.","Add a migration step that detects old-format metadata and upgrades it before load.","Verify the task was originally saved by a compatible version of the a2a-server code."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"import { isPersistedStateMetadata, METADATA_KEY } from '../types.js';\n\nfunction loadedMetadataHasPersistedState(loadedMetadata: unknown): boolean {\n  return (\n    typeof loadedMetadata === 'object' &&\n    loadedMetadata !== null &&\n    METADATA_KEY in loadedMetadata &&\n    isPersistedStateMetadata(\n      (loadedMetadata as Record<string, unknown>)[METADATA_KEY],\n    )\n  );\n}","tryCatchPattern":"try {\n  const task = await store.load(taskId);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('missing internal persisted state')) {\n    // The stored metadata is from an incompatible version or corrupted.\n    // Options: delete the stale GCS objects, run a migration, or recreate the task.\n    logger.warn(`Task ${taskId} has incompatible stored metadata. Recreating.`);\n  } else {\n    throw e;\n  }\n}","preventionTips":["Keep save and load code versions in sync during deployments.","Add a schema version field to persisted metadata to detect and migrate old formats.","Never manually edit metadata objects in the GCS bucket.","Run integration tests that round-trip save then load to catch schema drift."],"tags":["persistence","gcs","a2a","metadata","migration"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}