{"record":{"id":"2cba653f34e37ce8","repo":"HeyPuter/puter","slug":"subject-does-not-exist-2cba65","errorCode":"subject_does_not_exist","errorMessage":"entity_not_found: app:${targetAppUid}","messagePattern":"entity_not_found: app:(.+?)","errorType":"http","errorClass":"HttpError","httpStatus":404,"severity":"error","filePath":"src/backend/drivers/kv/KVStoreDriver.ts","lineNumber":214,"sourceCode":"        actor: Actor,\n        targetAppUid: string,\n        method: string,\n        args: KvCallArgs,\n    ): Promise<void> {\n        // `null` = no scope reaches it (`flush` is namespace-wide, not an\n        // entry op); `undefined` = unmapped method. Both fail closed.\n        const op = APP_DATA_KV_METHOD_OPS[method];\n        if (!op) {\n            throw new HttpError(\n                403,\n                `kv: \\`${method}\\` is not available on another app's data`,\n                { legacyCode: 'forbidden' },\n            );\n        }\n\n        const target = await this.stores.app.getByUid(targetAppUid);\n        if (!target) {\n            throw new HttpError(404, `entity_not_found: app:${targetAppUid}`, {\n                legacyCode: 'subject_does_not_exist',\n            });\n        }\n        if (!appDataSharingAllowed(target)) {\n            throw new HttpError(\n                403,\n                'kv: this app does not share its data with other apps',\n                { legacyCode: 'forbidden' },\n            );\n        }\n\n        if (\n            !(await this.services.permission.check(\n                actor,\n                appDataPermission(targetAppUid, 'kv', op),\n            ))\n        ) {\n            throw new HttpError(403, 'Permission denied', {","sourceCodeStart":196,"sourceCodeEnd":232,"githubUrl":"https://github.com/HeyPuter/puter/blob/908ec23eda38526170322c3edf71ba45ecb1ca95/src/backend/drivers/kv/KVStoreDriver.ts#L196-L232","documentation":"Thrown by KVStoreDriver's cross-app access path (#assertCrossAppKvAccess) when an app attempts to operate on another app's KV namespace (optConfig.appUuid differs from the actor's own app uid) but no app exists with the requested uid. The driver resolves the target via stores.app.getByUid and fails closed with 404 when nothing comes back. Legacy code subject_does_not_exist preserves the pre-v2 error shape callers matched on.","triggerScenarios":"Calling any kv method (get/set/incr/list/etc.) with optConfig.appUuid set to a uid that was never registered, was deleted, or is malformed — reached only when the caller's actor has an effectiveApp.uid and appUuid differs from it. E.g. kv.get({ key:'x', optConfig:{ appUuid:'app-deadbeef' } }) where that app uid is unknown.","commonSituations":"Stale app uid cached client-side after the target app was removed; copy-paste typo in the uid; passing the app's numeric id or name instead of its uid; test fixtures referencing an app that was never seeded; app uid harvested from a different environment (dev uid used against prod).","solutions":["Confirm you are passing the target app's uid (not its numeric id or name) in optConfig.appUuid.","Look up the target app fresh via the apps API before the kv call and use the returned uid.","If the target app was deleted, switch to a live app or omit appUuid to operate on your own namespace.","Regenerate and re-cache the target app uid rather than hardcoding it."],"exampleFix":"// before\nawait kv.get({ key:'pref', optConfig:{ appUuid: cachedTargetUid } });\n\n// after\nconst target = await apps.get(targetAppId);\nif (!target?.uid) throw new Error('target app unavailable');\nawait kv.get({ key:'pref', optConfig:{ appUuid: target.uid } });","handlingStrategy":"validation","validationCode":"// Resolve and verify the target app before any cross-app kv call.\nif (optConfig?.appUuid) {\n  const target = await apps.getByUid(optConfig.appUuid);\n  if (!target) {\n    throw new Error(`target app ${optConfig.appUuid} does not exist`);\n  }\n}\nawait kv.get({ key, optConfig });","typeGuard":"// App uid is an opaque string; only structural checks are meaningful.\nconst isAppUid = (v: unknown): v is string =>\n  typeof v === 'string' && v.startsWith('app-') && v.length > 4;","tryCatchPattern":"try {\n  await kv.get({ key, optConfig: { appUuid: targetUid } });\n} catch (e) {\n  if (e.status === 404 && e.code === 'subject_does_not_exist') {\n    // target app is gone — refresh uid cache or fall back to own namespace\n  } else throw e;\n}","preventionTips":["Always fetch the target app uid from the apps API at runtime; never hardcode it.","Cache uids with a TTL and re-resolve on 404.","Confirm you pass uid, not the numeric id or name."],"tags":["kv","cross-app","not-found","permissions","validation"],"backgroundTag":null,"analyzedSha":"908ec23eda38526170322c3edf71ba45ecb1ca95","analyzedAt":"2026-08-12T20:53:15.911Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}