{"record":{"id":"fb0b8277372f2604","repo":"TencentCloud/TencentDB-Agent-Memory","slug":"invalid-instance","errorCode":"INVALID_INSTANCE","errorMessage":"INVALID_INSTANCE","messagePattern":"INVALID_INSTANCE","errorType":"error_code","errorClass":"InstanceRegistryError","httpStatus":400,"severity":"error","filePath":"MemoryPanel/src/panel/config/instance-registry.ts","lineNumber":99,"sourceCode":"    }\n    const parsed = fileSchema.safeParse(raw);\n    if (!parsed.success) {\n      throw new InstanceRegistryError(500, `metadata instances config validation failed`);\n    }\n    const entries = parsed.data.instances.map((row) => ({\n      instance_id: row.id,\n      name: row.name,\n      gateway_endpoint: row.gateway_endpoint,\n      proxy_endpoint: row.proxy_endpoint,\n      api_key: row.api_key,\n    }));\n    return new InstanceRegistry(entries);\n  }\n\n  resolve(instanceId: string): InstanceEntry {\n    const entry = this.byId.get(instanceId);\n    if (!entry) {\n      throw new InstanceRegistryError(400, 'INVALID_INSTANCE');\n    }\n    return entry;\n  }\n\n  listPublic(): PublicInstance[] {\n    return [...this.byId.values()].map(({ instance_id, name, gateway_endpoint, proxy_endpoint }) => ({\n      instance_id,\n      name,\n      gateway_endpoint,\n      // 不填就不下发字段（不是显式 undefined，前端 `??` 回落更干净）\n      ...(proxy_endpoint ? { proxy_endpoint } : {}),\n    }));\n  }\n\n  /** Full entries incl. credentials — internal startup/admin use only, never client-facing. */\n  listAll(): InstanceEntry[] {\n    return [...this.byId.values()];\n  }","sourceCodeStart":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/3efcd317b84146d6a08518ac0f7ee7c8a8d200ec/MemoryPanel/src/panel/config/instance-registry.ts#L81-L117","documentation":"InstanceRegistry.resolve looks up an instance by id in its registry map and throws InstanceRegistryError(400, 'INVALID_INSTANCE') when the id is not present. It is an HTTP-facing validation: the client referenced an instance the panel does not know about.","triggerScenarios":"Any panel HTTP route that resolves an instanceId (e.g. file access via filePath) with an id that was never registered or has been removed from instances.json / the registry source.","commonSituations":"Stale instance id cached in a client after the registry was reloaded; typo or wrong env-provided instance id; instance removed/recreated with a new id while an agent still references the old one.","solutions":["Call the panel's instance list endpoint (listPublic) and use a valid instance_id","Re-register the missing instance in the registry config and reload","Fix the instanceId passed by the caller (check for stale references after redeploy)","Handle 400 INVALID_INSTANCE on the client by refreshing the instance list"],"exampleFix":"// before\nawait panel.get(`/instances/${oldId}/files`); // INVALID_INSTANCE\n// after\nconst { instances } = await panel.get('/instances');\nawait panel.get(`/instances/${instances[0].instance_id}/files`);","handlingStrategy":"try-catch","validationCode":"const known = await panel.get('/instances');\nif (!known.instances.some(i => i.instance_id === instanceId)) throw new Error(`unknown instance: ${instanceId}`);","typeGuard":null,"tryCatchPattern":"try { await panel.get(`/instances/${id}/files`); } catch (e) { if (e.status === 400 && e.code === 'INVALID_INSTANCE') { await refreshInstanceList(); } else throw e; }","preventionTips":["Refresh cached instance ids whenever the registry reloads","Validate instanceId against listPublic before calling instance-scoped routes","Treat instance ids as ephemeral; re-resolve after redeploys"],"tags":["http-400","validation","instance-registry"],"backgroundTag":"invalid-instance-id","analyzedSha":"3efcd317b84146d6a08518ac0f7ee7c8a8d200ec","analyzedAt":"2026-09-01T05:44:22.276Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}