{"record":{"id":"71205b2c2a0f3be0","repo":"openzipkin/zipkin","slug":"maxtracecols-0","errorCode":null,"errorMessage":"maxTraceCols <= 0","messagePattern":"maxTraceCols <= 0","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"zipkin-storage/cassandra/src/main/java/zipkin2/storage/cassandra/CassandraStorageBuilder.java","lineNumber":176,"sourceCode":"  }\n\n  public B ensureSchema(boolean ensureSchema) {\n    if (ensureSchema) {\n      this.ensureSchema = Schema::ensure;\n    } else {\n      this.ensureSchema = Schema::validate;\n    }\n    return (B) this;\n  }\n\n  /**\n   * Spans have multiple values for the same id. For example, a client and server contribute to the\n   * same span id. When searching for spans by id, the amount of results may be larger than the ids.\n   * This defines a threshold which accommodates this situation, without looking for an unbounded\n   * number of results.\n   */\n  public B maxTraceCols(int maxTraceCols) {\n    if (maxTraceCols <= 0) throw new IllegalArgumentException(\"maxTraceCols <= 0\");\n    this.maxTraceCols = maxTraceCols;\n    return (B) this;\n  }\n\n  /**\n   * How many more index rows to fetch than the user-supplied query limit. Defaults to 3.\n   *\n   * <p>Backend requests will request {@link QueryRequest#limit()} times this factor rows from\n   * Cassandra indexes in attempts to return {@link QueryRequest#limit()} traces.\n   *\n   * <p>Indexing in cassandra will usually have more rows than trace identifiers due to factors\n   * including table design and collection implementation. As there's no way to DISTINCT out\n   * duplicates server-side, this over-fetches client-side when {@code indexFetchMultiplier} &gt;\n   * 1.\n   */\n  public B indexFetchMultiplier(int indexFetchMultiplier) {\n    if (indexFetchMultiplier <= 0) throw new IllegalArgumentException(\"indexFetchMultiplier <= 0\");\n    this.indexFetchMultiplier = indexFetchMultiplier;","sourceCodeStart":158,"sourceCodeEnd":194,"githubUrl":"https://github.com/openzipkin/zipkin/blob/878ce2a1fad54ca941d17fdcf2e1d924b148eb1f/zipkin-storage/cassandra/src/main/java/zipkin2/storage/cassandra/CassandraStorageBuilder.java#L158-L194","documentation":"Thrown by CassandraStorageBuilder.maxTraceCols(int) when the value is zero or negative. maxTraceCols caps how many span rows are fetched per trace id because a single span id can have multiple rows (client and server share a span id). The guard prevents an unbounded or nonsensical fetch size.","triggerScenarios":"Calling maxTraceCols(0) or maxTraceCols(-5) on CassandraStorage.newBuilder(); computing the value from user input or config that defaulted to 0 when parsing failed.","commonSituations":"Setting maxTraceCols from an environment variable or properties file where a typo or missing value parses to 0; porting older configs that used a different name.","solutions":["Set a positive value, e.g. maxTraceCols(10000) (the documented default is 10000).","Validate the config-sourced integer before passing it: reject or default values <= 0 at load time."],"exampleFix":"// before\n.maxTraceCols(Integer.parseInt(System.getenv(\"MAX_TRACE_COLS\"))) // env unset -> 0\n\n// after\nint maxTraceCols = Integer.parseInt(System.getenv().getOrDefault(\"MAX_TRACE_COLS\", \"10000\"));\nif (maxTraceCols <= 0) throw new IllegalArgumentException(\"MAX_TRACE_COLS must be > 0\");\n.maxTraceCols(maxTraceCols)","handlingStrategy":"validation","validationCode":"int maxTraceCols = config.getInt(\"cassandra.max-trace-cols\", 10000);\nif (maxTraceCols <= 0) throw new IllegalArgumentException(\"maxTraceCols must be > 0, got \" + maxTraceCols);\nbuilder.maxTraceCols(maxTraceCols);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate positive-integer config values at load time with clear messages including the property name.","Omit the setter entirely to keep the documented default."],"tags":["cassandra","zipkin","builder","validation","configuration"],"backgroundTag":null,"analyzedSha":"878ce2a1fad54ca941d17fdcf2e1d924b148eb1f","analyzedAt":"2026-08-14T15:17:09.895Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}