{"record":{"id":"d730941d2556090c","repo":"oven-sh/bun","slug":"typename-internal-true-on-a-property-is-not","errorCode":null,"errorMessage":"${typeName}: 'internal: true' on a property is not implemented (no users today; the visitChildren plumbing for it was never wired up consistently). Use 'cache: true' or add it to 'values' instead.","messagePattern":"(.+?): 'internal: true' on a property is not implemented \\(no users today; the visitChildren plumbing for it was never wired up consistently\\)\\. Use 'cache: true' or add it to 'values' instead\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/codegen/generate-classes.ts","lineNumber":1064,"sourceCode":"      values.push([name, cacheName]);\n    }\n  }\n\n  return values;\n}\n\nfunction generateClassHeader(typeName, obj: ClassDefinition) {\n  var { klass, proto, JSType = \"ObjectType\", values = [] } = obj;\n\n  const name = className(typeName);\n\n  if (obj.estimatedSize) {\n    externs += `extern JSC_CALLCONV size_t ${symbolName(typeName, \"estimatedSize\")}(void* ptr);` + \"\\n\";\n  }\n\n  for (const a of [...Object.values(klass), ...Object.values(proto)]) {\n    if (a.internal === true) {\n      throw new Error(\n        `${typeName}: 'internal: true' on a property is not implemented (no users today; the visitChildren plumbing for it was never wired up consistently). Use 'cache: true' or add it to 'values' instead.`,\n      );\n    }\n  }\n  const DECLARE_VISIT_CHILDREN =\n    values.length ||\n    obj.estimatedSize ||\n    obj.valuesArray ||\n    [...Object.values(klass), ...Object.values(proto)].find(a => a.cache === true)\n      ? \"DECLARE_VISIT_CHILDREN;\\n\"\n      : \"\";\n\n  var weakOwner = \"\";\n  var weakInit = ``;\n  if (obj.hasPendingActivity) {\n    weakInit = `m_weakThis = JSC::Weak<${name}>(this, getOwner());`;\n    weakOwner = `\n    JSC::Weak<${name}> m_weakThis;","sourceCodeStart":1046,"sourceCodeEnd":1082,"githubUrl":"https://github.com/oven-sh/bun/blob/8c5296ac459e8252d3cd702f3fbcbb0c249d95d5/src/codegen/generate-classes.ts#L1046-L1082","documentation":"A deliberate guard in generate-classes.ts: properties in *.classes.ts files cannot use `internal: true`. Although the option appears in the schema, the GC visitChildren plumbing it implies was never wired up consistently, so the generator hard-rejects it instead of emitting broken tracing code. The message points at the two supported alternatives: `cache: true` (getter whose result is cached and traced) or adding the slot to the class `values` array.","triggerScenarios":"Declaring any klass or proto property with `internal: true` in a .classes.ts file, e.g. `proto: { underlying: { internal: true } }`, then running the class codegen step.","commonSituations":"Contributors trying to expose an internal accessor for C++/Rust-side state without making it a full cached property; copying old definitions from before the guard existed.","solutions":["Replace `internal: true` with `cache: true` if the property is a JS-visible getter whose value should be retained and GC-traced","Or declare the field in the class's `values` array so it participates in visitChildren through the normal values plumbing","If neither fits, the property likely should not be in the definition at all — implement it as a manual C++/Rust method"],"exampleFix":"// before (Foo.classes.ts)\nproto: {\n  socket: { internal: true },\n}\n\n// after\nproto: {\n  socket: { cache: true },\n}","handlingStrategy":"validation","validationCode":"// reject `internal: true` before running codegen\nfor (const [name, prop] of Object.entries({ ...obj.klass, ...obj.proto })) {\n  if ((prop as any)?.internal === true) {\n    throw new Error(`${obj.name}.${name}: internal: true is not implemented — use cache: true or values`);\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Model retained per-instance JS-visible state with cache: true or the values array; `internal` is dead schema","If you need untraced native state, keep it as plain Rust/C++ fields, not a class-definition property"],"tags":["codegen","classes","garbage-collector","bindings"],"backgroundTag":null,"analyzedSha":"8c5296ac459e8252d3cd702f3fbcbb0c249d95d5","analyzedAt":"2026-08-16T08:01:58.794Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}