TencentCloud/TencentDB-Agent-Memory · error · InstanceRegistryError

INVALID_INSTANCE

INVALID_INSTANCE

Error message

INVALID_INSTANCE

What it means

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.

Source

Thrown at MemoryPanel/src/panel/config/instance-registry.ts:99

    }
    const parsed = fileSchema.safeParse(raw);
    if (!parsed.success) {
      throw new InstanceRegistryError(500, `metadata instances config validation failed`);
    }
    const entries = parsed.data.instances.map((row) => ({
      instance_id: row.id,
      name: row.name,
      gateway_endpoint: row.gateway_endpoint,
      proxy_endpoint: row.proxy_endpoint,
      api_key: row.api_key,
    }));
    return new InstanceRegistry(entries);
  }

  resolve(instanceId: string): InstanceEntry {
    const entry = this.byId.get(instanceId);
    if (!entry) {
      throw new InstanceRegistryError(400, 'INVALID_INSTANCE');
    }
    return entry;
  }

  listPublic(): PublicInstance[] {
    return [...this.byId.values()].map(({ instance_id, name, gateway_endpoint, proxy_endpoint }) => ({
      instance_id,
      name,
      gateway_endpoint,
      // 不填就不下发字段（不是显式 undefined，前端 `??` 回落更干净）
      ...(proxy_endpoint ? { proxy_endpoint } : {}),
    }));
  }

  /** Full entries incl. credentials — internal startup/admin use only, never client-facing. */
  listAll(): InstanceEntry[] {
    return [...this.byId.values()];
  }

View on GitHub (pinned to 3efcd317b8)

Solutions

1. Call the panel's instance list endpoint (listPublic) and use a valid instance_id
2. Re-register the missing instance in the registry config and reload
3. Fix the instanceId passed by the caller (check for stale references after redeploy)
4. Handle 400 INVALID_INSTANCE on the client by refreshing the instance list

Example fix

// before
await panel.get(`/instances/${oldId}/files`); // INVALID_INSTANCE
// after
const { instances } = await panel.get('/instances');
await panel.get(`/instances/${instances[0].instance_id}/files`);

const known = await panel.get('/instances');
if (!known.instances.some(i => i.instance_id === instanceId)) throw new Error(`unknown instance: ${instanceId}`);

try { await panel.get(`/instances/${id}/files`); } catch (e) { if (e.status === 400 && e.code === 'INVALID_INSTANCE') { await refreshInstanceList(); } else throw e; }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• memory 系统用户 key 必须匹配 sk-mem-[A-Za-z0-9_-]{32}
• llm.provider=proxy 且 useMemorySystemUserKey=false 时必须显式 llm.
• Generation log object key exceeds COS limit
• Invalid generation log key
• Invalid generation log cursor

AI-assisted analysis of TencentCloud/TencentDB-Agent-Memory@3efcd317b8 (2026-09-01). Data as JSON: /api/errors/fb0b8277372f2604. Report an issue: GitHub.