{"record":{"id":"b8fa0d26263cd418","repo":"can1357/oh-my-pi","slug":"host-uri-scheme-is-reserved-by-omp-scheme","errorCode":null,"errorMessage":"Host URI scheme is reserved by OMP: ${scheme}://","messagePattern":"Host URI scheme is reserved by OMP: (.+?)://","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/coding-agent/src/modes/rpc/host-uris.ts","lineNumber":101,"sourceCode":"\t}\n\n\t/**\n\t * Replace the registered set of host URI schemes. Previously registered\n\t * schemes that no longer appear in the new set are unregistered from the\n\t * router; surviving and new schemes get fresh handler instances.\n\t */\n\tsetSchemes(schemes: RpcHostUriSchemeDefinition[]): string[] {\n\t\tconst normalized = new Map<string, RpcHostUriSchemeDefinition>();\n\t\tfor (const raw of schemes) {\n\t\t\tconst scheme = typeof raw?.scheme === \"string\" ? raw.scheme.trim().toLowerCase() : \"\";\n\t\t\tif (!scheme) {\n\t\t\t\tthrow new Error(\"Host URI scheme must be a non-empty string\");\n\t\t\t}\n\t\t\tif (!/^[a-z][a-z0-9+.-]*$/.test(scheme)) {\n\t\t\t\tthrow new Error(`Host URI scheme contains invalid characters: ${raw.scheme}`);\n\t\t\t}\n\t\t\tif (RESERVED_HOST_URI_SCHEMES.has(scheme)) {\n\t\t\t\tthrow new Error(`Host URI scheme is reserved by OMP: ${scheme}://`);\n\t\t\t}\n\t\t\tnormalized.set(scheme, {\n\t\t\t\tscheme,\n\t\t\t\tdescription: typeof raw.description === \"string\" ? raw.description : undefined,\n\t\t\t\twritable: raw.writable === true,\n\t\t\t\timmutable: raw.immutable === true,\n\t\t\t});\n\t\t}\n\n\t\tfor (const previous of this.#definitions.keys()) {\n\t\t\tif (!normalized.has(previous)) {\n\t\t\t\tthis.#router.unregister(previous);\n\t\t\t}\n\t\t}\n\t\tfor (const definition of normalized.values()) {\n\t\t\tthis.#router.register(new RpcHostUriProtocolHandler(definition, this));\n\t\t}\n\t\tthis.#definitions = normalized;","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/coding-agent/src/modes/rpc/host-uris.ts#L83-L119","documentation":"A set of scheme names reserved by OMP (RESERVED_HOST_URI_SCHEMES) cannot be registered by external/RPC callers, to prevent collisions with built-in host URI handlers. Registering such a scheme throws immediately with the colliding name.","triggerScenarios":"Calling setSchemes with a scheme whose lowercased name is present in RESERVED_HOST_URI_SCHEMES (built-in OMP schemes) — e.g. attempting to override a scheme like \"file\" or another internal scheme.","commonSituations":"A plugin/RPC client trying to shadow a built-in host URI scheme; a generic config reusing a common word (e.g. \"app\", \"file\") that happens to be reserved; migration from a setup where the scheme was previously allowed.","solutions":["Rename the scheme to something namespaced and unreserved (e.g. myplugin-docs instead of the reserved name)","Check the reserved list in host-uris.ts and pick a non-colliding name before registering","If you need built-in-scheme behavior, use the built-in handler rather than registering a duplicate"],"exampleFix":"// before\nsetSchemes([{ scheme: \"file\", description: \"custom files\" }]);\n// after\nsetSchemes([{ scheme: \"myapp-file\", description: \"custom files\" }]);","handlingStrategy":"validation","validationCode":"import { RESERVED_HOST_URI_SCHEMES } from \"./host-uris\"; // or inline the known reserved set\nif (RESERVED_HOST_URI_SCHEMES.has(scheme.trim().toLowerCase())) throw new Error(`Scheme ${scheme} is reserved`);","typeGuard":"function isRegisterableScheme(s: string, reserved: Set<string>): boolean {\n  const norm = s.trim().toLowerCase();\n  return norm !== \"\" && !reserved.has(norm);\n}","tryCatchPattern":"try {\n  hostUris.setSchemes(defs);\n} catch (err) {\n  if (err.message.startsWith(\"Host URI scheme is reserved\")) {\n    logger.warn(\"Renaming reserved scheme\", { raw: err.message });\n    hostUris.setSchemes(defs.map(d => RESERVED.has(d.scheme) ? { ...d, scheme: nsPrefix(d.scheme) } : d));\n  } else throw err;\n}","preventionTips":["Namespace custom schemes with a plugin/app prefix to avoid built-in collisions","Check the reserved scheme list before choosing a name","Never attempt to override built-in host URI handlers","Keep a config lint that flags reserved scheme names"],"tags":["validation","rpc","host-uri","namespace-collision"],"backgroundTag":"reserved-uri-scheme","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}