{"record":{"id":"b7242bbcdd139014","repo":"ruvnet/ruflo","slug":"string-length-len-exceeds-remaining-buffer","errorCode":null,"errorMessage":"String length ${len} exceeds remaining buffer","messagePattern":"String length (.+?) exceeds remaining buffer","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/appliance/gguf-engine.ts","lineNumber":99,"sourceCode":"  readU8(): number  { const v = this.buf.readUInt8(this.offset); this.offset += 1; return v; }\n  readI8(): number  { const v = this.buf.readInt8(this.offset); this.offset += 1; return v; }\n  readU16(): number { const v = this.buf.readUInt16LE(this.offset); this.offset += 2; return v; }\n  readI16(): number { const v = this.buf.readInt16LE(this.offset); this.offset += 2; return v; }\n  readU32(): number { const v = this.buf.readUInt32LE(this.offset); this.offset += 4; return v; }\n  readI32(): number { const v = this.buf.readInt32LE(this.offset); this.offset += 4; return v; }\n  readF32(): number { const v = this.buf.readFloatLE(this.offset); this.offset += 4; return v; }\n  readF64(): number { const v = this.buf.readDoubleLE(this.offset); this.offset += 8; return v; }\n  readU64(): bigint { const v = this.buf.readBigUInt64LE(this.offset); this.offset += 8; return v; }\n  readI64(): bigint { const v = this.buf.readBigInt64LE(this.offset); this.offset += 8; return v; }\n  /** Safe for values up to 2^53. Real GGUF files never exceed this for tensor/kv counts. */\n  readU64AsNumber(): number { return Number(this.readU64()); }\n  readBool(): boolean { return this.readU8() !== 0; }\n\n  /** GGUF string: [length u64 LE][utf-8 bytes]. */\n  readString(): string {\n    const len = this.readU64AsNumber();\n    if (len === 0) return '';\n    if (len > this.remaining) throw new Error(`String length ${len} exceeds remaining buffer`);\n    const s = this.buf.toString('utf-8', this.offset, this.offset + len);\n    this.offset += len;\n    return s;\n  }\n}\n\n// ── GGUF Value Reading ──────────────────────────────────────\n\n/** Read a typed scalar from the buffer (shared by value and array-element readers). */\nfunction readScalar(reader: BufferReader, t: number): unknown {\n  switch (t) {\n    case GgufValueType.UINT8:   return reader.readU8();\n    case GgufValueType.INT8:    return reader.readI8();\n    case GgufValueType.UINT16:  return reader.readU16();\n    case GgufValueType.INT16:   return reader.readI16();\n    case GgufValueType.UINT32:  return reader.readU32();\n    case GgufValueType.INT32:   return reader.readI32();\n    case GgufValueType.FLOAT32: return reader.readF32();","sourceCodeStart":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/ruvnet/ruflo/blob/6b01dc5a687b26b3e218f796de45ec51f8fa9e8c/v3/@claude-flow/cli/src/appliance/gguf-engine.ts#L81-L117","documentation":"Thrown by BufferReader.readString while parsing a GGUF file. GGUF strings are encoded as a u64 length prefix followed by UTF-8 bytes; readString reads the length with readU64AsNumber and rejects it if it exceeds reader.remaining. This protects against truncated or malformed files that would otherwise read past the buffer end (the parse reads at most the first 256 KB of the file, so legitimate large strings can still trip this).","triggerScenarios":"Parsing a GGUF file whose metadata declares a string longer than the bytes left in the 256 KB header window, a file truncated mid-metadata, or a corrupt length prefix (e.g. garbage read as u64). Also possible for models with unusually large string metadata that exceeds the 256 KB read window.","commonSituations":"Downloading a model file incompletely (truncated transfer), pointing parseGgufHeader at a non-GGUF file, or a model whose tokenizer vocabulary is stored as one giant string exceeding the 256 KB cap. The catch in parseGgufBuffer swallows some of these during the KV loop, but the throw still propagates elsewhere.","solutions":["Verify the file is a complete, valid GGUF (check file size against the source, re-download if truncated).","Confirm you are pointing at a real GGUF file and not a different format renamed .gguf.","If the model legitimately has very large metadata strings, the 256 KB header window in parseGgufHeader is the limit — request/produce a GGUF with smaller string metadata or extend the read size.","Validate the file with an external GGUF inspector (e.g. llama.cpp) to isolate corruption from parser limitations."],"exampleFix":"// before\nconst meta = await parseGgufHeader('/models/possibly-corrupt.gguf');\n\n// after\nconst stat = await fsStat(path);\nif (stat.size < 1024) throw new Error('file too small to be a valid GGUF');\nconst meta = await parseGgufHeader(path);","handlingStrategy":"validation","validationCode":"const stat = await fsStat(path);\nif (stat.size < 1024) {\n  throw new Error('file too small to be a valid GGUF');\n}\nconst meta = await parseGgufHeader(path);","typeGuard":"function looksLikeCompleteGguf(stat: { size: number }): boolean {\n  return stat.size >= 1024; // heuristic: a real GGUF is at least kilobytes\n}","tryCatchPattern":"try {\n  return await parseGgufHeader(path);\n} catch (e) {\n  if (e instanceof Error && /exceeds remaining buffer/.test(e.message)) {\n    logger.error({ path }, 'GGUF truncated or corrupt');\n  }\n  throw e;\n}","preventionTips":["Verify file size matches the source before parsing.","Re-download incomplete files.","Do not parse non-.gguf files.","Validate with a reference GGUF reader when in doubt."],"tags":["gguf","binary-parsing","file-format","appliance"],"backgroundTag":null,"analyzedSha":"6b01dc5a687b26b3e218f796de45ec51f8fa9e8c","analyzedAt":"2026-08-12T13:20:50.148Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}