[{"data":1,"prerenderedAt":894},["ShallowReactive",2],{"doc:\u002Fguides\u002Ferrors":3,"nav:guides":846},{"doc":4,"source":845},{"id":5,"title":6,"body":7,"description":17,"extension":839,"meta":840,"navigation":623,"path":841,"seo":842,"stem":843,"__hash__":844},"guides\u002Fguides\u002Ferrors.md","Errors",{"type":8,"value":9,"toc":832},"minimark",[10,14,18,23,268,285,291,295,441,447,453,505,509,519,703,719,723,783,794,798,819,828],[11,12,6],"h1",{"id":13},"errors",[15,16,17],"p",{},"zig-pkl reports failures as Zig errors. When Pkl explains a failure, the explanation is returned through an out parameter that the caller frees.",[19,20,22],"h2",{"id":21},"evaluation-failures","Evaluation failures",[24,25,30],"pre",{"className":26,"code":27,"language":28,"meta":29,"style":29},"language-zig shiki shiki-themes github-light github-dark","var failure: ?[]u8 = null;\ndefer if (failure) |text| allocator.free(text);\nvar tree = evaluator.evaluateSource(source, null, &failure) catch |err| switch (err) {\n    error.EvaluationFailed => {\n        std.debug.print(\"{s}\\n\", .{failure.?});\n        return err;\n    },\n    else => return err,\n};\n","zig","",[31,32,33,68,112,171,188,229,240,246,262],"code",{"__ignoreMap":29},[34,35,38,42,46,50,53,56,59,62,65],"span",{"class":36,"line":37},"line",1,[34,39,41],{"class":40},"szBVR","var",[34,43,45],{"class":44},"s4XuR"," failure",[34,47,49],{"class":48},"sVt8B",": ",[34,51,52],{"class":40},"?",[34,54,55],{"class":48},"[]",[34,57,58],{"class":40},"u8",[34,60,61],{"class":40}," =",[34,63,64],{"class":40}," null",[34,66,67],{"class":48},";\n",[34,69,71,74,77,80,83,86,89,92,94,97,100,104,107,109],{"class":36,"line":70},2,[34,72,73],{"class":40},"defer",[34,75,76],{"class":40}," if",[34,78,79],{"class":48}," (",[34,81,82],{"class":44},"failure",[34,84,85],{"class":48},") ",[34,87,88],{"class":40},"|",[34,90,91],{"class":44},"text",[34,93,88],{"class":40},[34,95,96],{"class":44}," allocator",[34,98,99],{"class":48},".",[34,101,103],{"class":102},"sScJk","free",[34,105,106],{"class":48},"(",[34,108,91],{"class":44},[34,110,111],{"class":48},");\n",[34,113,115,117,120,122,125,127,130,132,135,138,141,143,146,148,150,153,156,159,161,164,166,168],{"class":36,"line":114},3,[34,116,41],{"class":40},[34,118,119],{"class":44}," tree",[34,121,61],{"class":40},[34,123,124],{"class":44}," evaluator",[34,126,99],{"class":48},[34,128,129],{"class":102},"evaluateSource",[34,131,106],{"class":48},[34,133,134],{"class":44},"source",[34,136,137],{"class":48},", ",[34,139,140],{"class":40},"null",[34,142,137],{"class":48},[34,144,145],{"class":40},"&",[34,147,82],{"class":44},[34,149,85],{"class":48},[34,151,152],{"class":40},"catch",[34,154,155],{"class":40}," |",[34,157,158],{"class":44},"err",[34,160,88],{"class":40},[34,162,163],{"class":40}," switch",[34,165,79],{"class":48},[34,167,158],{"class":44},[34,169,170],{"class":48},") {\n",[34,172,174,177,179,182,185],{"class":36,"line":173},4,[34,175,176],{"class":40},"    error",[34,178,99],{"class":48},[34,180,181],{"class":44},"EvaluationFailed",[34,183,184],{"class":40}," =>",[34,186,187],{"class":48}," {\n",[34,189,191,194,196,199,201,204,206,210,214,217,220,222,224,226],{"class":36,"line":190},5,[34,192,193],{"class":44},"        std",[34,195,99],{"class":48},[34,197,198],{"class":44},"debug",[34,200,99],{"class":48},[34,202,203],{"class":102},"print",[34,205,106],{"class":48},[34,207,209],{"class":208},"sZZnC","\"{s}",[34,211,213],{"class":212},"sj4cs","\\n",[34,215,216],{"class":208},"\"",[34,218,219],{"class":48},", .{",[34,221,82],{"class":44},[34,223,99],{"class":48},[34,225,52],{"class":40},[34,227,228],{"class":48},"});\n",[34,230,232,235,238],{"class":36,"line":231},6,[34,233,234],{"class":40},"        return",[34,236,237],{"class":44}," err",[34,239,67],{"class":48},[34,241,243],{"class":36,"line":242},7,[34,244,245],{"class":48},"    },\n",[34,247,249,252,254,257,259],{"class":36,"line":248},8,[34,250,251],{"class":40},"    else",[34,253,184],{"class":40},[34,255,256],{"class":40}," return",[34,258,237],{"class":44},[34,260,261],{"class":48},",\n",[34,263,265],{"class":36,"line":264},9,[34,266,267],{"class":48},"};\n",[15,269,270,273,274,277,278,280,281,284],{},[31,271,272],{},"error.EvaluationFailed"," means Pkl evaluated the request and reported an error: a type constraint, a missing property, a denied import, a ",[31,275,276],{},"throw",". ",[31,279,82],{}," then holds Pkl's full message, allocated with the manager's allocator. The message starts with a ",[31,282,283],{},"–– Pkl Error ––"," banner, then the reason, then the source location.",[15,286,287,288,290],{},"Reuse one ",[31,289,82],{}," variable across calls only if you free it between them; each failing call overwrites it.",[19,292,294],{"id":293},"rejected-evaluators","Rejected evaluators",[24,296,298],{"className":26,"code":297,"language":28,"meta":29,"style":29},"var rejected: ?[]u8 = null;\ndefer if (rejected) |text| allocator.free(text);\nconst evaluator = manager.createEvaluator(options, &rejected) catch |err| switch (err) {\n    error.Rejected => return reportRejected(rejected.?),\n    else => return err,\n};\n",[31,299,300,321,352,398,425,437],{"__ignoreMap":29},[34,301,302,304,307,309,311,313,315,317,319],{"class":36,"line":37},[34,303,41],{"class":40},[34,305,306],{"class":44}," rejected",[34,308,49],{"class":48},[34,310,52],{"class":40},[34,312,55],{"class":48},[34,314,58],{"class":40},[34,316,61],{"class":40},[34,318,64],{"class":40},[34,320,67],{"class":48},[34,322,323,325,327,329,332,334,336,338,340,342,344,346,348,350],{"class":36,"line":70},[34,324,73],{"class":40},[34,326,76],{"class":40},[34,328,79],{"class":48},[34,330,331],{"class":44},"rejected",[34,333,85],{"class":48},[34,335,88],{"class":40},[34,337,91],{"class":44},[34,339,88],{"class":40},[34,341,96],{"class":44},[34,343,99],{"class":48},[34,345,103],{"class":102},[34,347,106],{"class":48},[34,349,91],{"class":44},[34,351,111],{"class":48},[34,353,354,357,359,361,364,366,369,371,374,376,378,380,382,384,386,388,390,392,394,396],{"class":36,"line":114},[34,355,356],{"class":40},"const",[34,358,124],{"class":44},[34,360,61],{"class":40},[34,362,363],{"class":44}," manager",[34,365,99],{"class":48},[34,367,368],{"class":102},"createEvaluator",[34,370,106],{"class":48},[34,372,373],{"class":44},"options",[34,375,137],{"class":48},[34,377,145],{"class":40},[34,379,331],{"class":44},[34,381,85],{"class":48},[34,383,152],{"class":40},[34,385,155],{"class":40},[34,387,158],{"class":44},[34,389,88],{"class":40},[34,391,163],{"class":40},[34,393,79],{"class":48},[34,395,158],{"class":44},[34,397,170],{"class":48},[34,399,400,402,404,407,409,411,414,416,418,420,422],{"class":36,"line":173},[34,401,176],{"class":40},[34,403,99],{"class":48},[34,405,406],{"class":44},"Rejected",[34,408,184],{"class":40},[34,410,256],{"class":40},[34,412,413],{"class":102}," reportRejected",[34,415,106],{"class":48},[34,417,331],{"class":44},[34,419,99],{"class":48},[34,421,52],{"class":40},[34,423,424],{"class":48},"),\n",[34,426,427,429,431,433,435],{"class":36,"line":190},[34,428,251],{"class":40},[34,430,184],{"class":40},[34,432,256],{"class":40},[34,434,237],{"class":44},[34,436,261],{"class":48},[34,438,439],{"class":36,"line":231},[34,440,267],{"class":48},[15,442,443,444,99],{},"Pkl rejects settings it cannot use, such as an allow list entry that is not a valid regular expression. Before Pkl 0.29 that particular mistake makes the server exit instead, which surfaces as ",[31,445,446],{},"error.Closed",[15,448,449,450,452],{},"Other errors from ",[31,451,368],{},":",[454,455,456,469],"table",{},[457,458,459],"thead",{},[460,461,462,466],"tr",{},[463,464,465],"th",{},"Error",[463,467,468],{},"Meaning",[470,471,472,491],"tbody",{},[460,473,474,480],{},[475,476,477],"td",{},[31,478,479],{},"error.NoAllowedModules",[475,481,482,485,486],{},[31,483,484],{},"allowed_modules"," is null or empty; see ",[487,488,490],"a",{"href":489},"security","Security",[460,492,493,498],{},[475,494,495],{},[31,496,497],{},"error.UnsupportedVersion",[475,499,500,501],{},"the options use a feature the server's Pkl release lacks; see ",[487,502,504],{"href":503},"compatibility","Version compatibility",[19,506,508],{"id":507},"timeouts-and-cancellation","Timeouts and cancellation",[15,510,511,514,515,518],{},[31,512,513],{},"evaluateWithOptions"," and ",[31,516,517],{},"createEvaluatorWithOptions"," accept a client-side deadline and a cancellation flag:",[24,520,522],{"className":26,"code":521,"language":28,"meta":29,"style":29},"var tree = try evaluator.evaluateWithOptions(\"repl:text\", text, null, &failure, .{\n    .timeout = .{ .duration = .{ .raw = .fromMilliseconds(250), .clock = .awake } },\n});\n\nvar cancellation = zig_pkl.Cancellation{};\n\u002F\u002F another thread: cancellation.cancel();\nvar other = try evaluator.evaluateWithOptions(uri, null, null, &failure, .{ .cancellation = &cancellation });\n",[31,523,524,563,615,619,625,645,651],{"__ignoreMap":29},[34,525,526,528,530,532,535,537,539,541,543,546,548,550,552,554,556,558,560],{"class":36,"line":37},[34,527,41],{"class":40},[34,529,119],{"class":44},[34,531,61],{"class":40},[34,533,534],{"class":40}," try",[34,536,124],{"class":44},[34,538,99],{"class":48},[34,540,513],{"class":102},[34,542,106],{"class":48},[34,544,545],{"class":208},"\"repl:text\"",[34,547,137],{"class":48},[34,549,91],{"class":44},[34,551,137],{"class":48},[34,553,140],{"class":40},[34,555,137],{"class":48},[34,557,145],{"class":40},[34,559,82],{"class":44},[34,561,562],{"class":48},", .{\n",[34,564,565,568,571,573,576,579,581,583,586,588,591,594,596,599,602,605,607,609,612],{"class":36,"line":70},[34,566,567],{"class":48},"    .",[34,569,570],{"class":44},"timeout",[34,572,61],{"class":40},[34,574,575],{"class":48}," .{ .",[34,577,578],{"class":44},"duration",[34,580,61],{"class":40},[34,582,575],{"class":48},[34,584,585],{"class":44},"raw",[34,587,61],{"class":40},[34,589,590],{"class":48}," .",[34,592,593],{"class":102},"fromMilliseconds",[34,595,106],{"class":48},[34,597,598],{"class":212},"250",[34,600,601],{"class":48},"), .",[34,603,604],{"class":44},"clock",[34,606,61],{"class":40},[34,608,590],{"class":48},[34,610,611],{"class":44},"awake",[34,613,614],{"class":48}," } },\n",[34,616,617],{"class":36,"line":114},[34,618,228],{"class":48},[34,620,621],{"class":36,"line":173},[34,622,624],{"emptyLinePlaceholder":623},true,"\n",[34,626,627,629,632,634,637,639,642],{"class":36,"line":190},[34,628,41],{"class":40},[34,630,631],{"class":44}," cancellation",[34,633,61],{"class":40},[34,635,636],{"class":44}," zig_pkl",[34,638,99],{"class":48},[34,640,641],{"class":44},"Cancellation",[34,643,644],{"class":48},"{};\n",[34,646,647],{"class":36,"line":231},[34,648,650],{"class":649},"sJ8bj","\u002F\u002F another thread: cancellation.cancel();\n",[34,652,653,655,658,660,662,664,666,668,670,673,675,677,679,681,683,685,687,690,693,695,698,700],{"class":36,"line":242},[34,654,41],{"class":40},[34,656,657],{"class":44}," other",[34,659,61],{"class":40},[34,661,534],{"class":40},[34,663,124],{"class":44},[34,665,99],{"class":48},[34,667,513],{"class":102},[34,669,106],{"class":48},[34,671,672],{"class":44},"uri",[34,674,137],{"class":48},[34,676,140],{"class":40},[34,678,137],{"class":48},[34,680,140],{"class":40},[34,682,137],{"class":48},[34,684,145],{"class":40},[34,686,82],{"class":44},[34,688,689],{"class":48},", .{ .",[34,691,692],{"class":44},"cancellation",[34,694,61],{"class":40},[34,696,697],{"class":40}," &",[34,699,692],{"class":44},[34,701,702],{"class":48}," });\n",[15,704,705,706,514,709,712,713,716,717,99],{},"They return ",[31,707,708],{},"error.Timeout",[31,710,711],{},"error.Canceled",". The client stops waiting, but the server keeps evaluating until it finishes; its late answer is discarded. To bound the server's own work, set ",[31,714,715],{},"Options.timeout_seconds",", which Pkl enforces and reports as ",[31,718,272],{},[19,720,722],{"id":721},"connection-failures","Connection failures",[454,724,725,733],{},[457,726,727],{},[460,728,729,731],{},[463,730,465],{},[463,732,468],{},[470,734,735,748,757,767],{},[460,736,737,742],{},[475,738,739],{},[31,740,741],{},"error.FileNotFound",[475,743,744,747],{},[31,745,746],{},"Manager.init"," could not start the server command",[460,749,750,754],{},[475,751,752],{},[31,753,446],{},[475,755,756],{},"the server exited, its pipes closed, or the manager is shutting down",[460,758,759,764],{},[475,760,761],{},[31,762,763],{},"error.Protocol",[475,765,766],{},"the server sent a response that does not fit the request",[460,768,769,780],{},[475,770,771,137,774,137,777],{},[31,772,773],{},"error.InvalidMessage",[31,775,776],{},"error.UnknownCode",[31,778,779],{},"error.LimitExceeded",[475,781,782],{},"a frame could not be decoded within the limits",[15,784,785,786,789,790,793],{},"These are terminal for the manager: pending and later requests fail with the same error, and ",[31,787,788],{},"Manager.failure()"," returns it. ",[31,791,792],{},"Manager.serverStderr(allocator)"," returns the last part of the server's standard error, which usually says why it exited.",[19,795,797],{"id":796},"decoding","Decoding",[15,799,800,514,803,806,807,810,811,814,815,818],{},[31,801,802],{},"convert.into",[31,804,805],{},"evaluateInto"," return ",[31,808,809],{},"error.TypeMismatch"," when a value does not fit the Zig type, ",[31,812,813],{},"error.MissingField"," when a struct field without a default has no matching property, and ",[31,816,817],{},"error.Overflow"," when an integer does not fit.",[15,820,821,827],{},[487,822,824],{"href":823},"..\u002F..\u002Fexamples\u002Ferrors\u002Fmain.zig",[31,825,826],{},"examples\u002Ferrors"," shows each case against a live server.",[829,830,831],"style",{},"html pre.shiki code .szBVR, html code.shiki .szBVR{--shiki-default:#D73A49;--shiki-dark:#F97583}html pre.shiki code .s4XuR, html code.shiki .s4XuR{--shiki-default:#E36209;--shiki-dark:#FFAB70}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sJ8bj, html code.shiki .sJ8bj{--shiki-default:#6A737D;--shiki-dark:#6A737D}",{"title":29,"searchDepth":70,"depth":70,"links":833},[834,835,836,837,838],{"id":21,"depth":70,"text":22},{"id":293,"depth":70,"text":294},{"id":507,"depth":70,"text":508},{"id":721,"depth":70,"text":722},{"id":796,"depth":70,"text":797},"md",{},"\u002Fguides\u002Ferrors",{"title":6,"description":17},"guides\u002Ferrors","cgCxICyE7POGa1XotBU0YQA4iwaAqVzo1Ty-c-4fCxY","docs\u002Fguides\u002Ferrors.md",[847,850,854,855,859,863,867,871,875,879,883,887,891],{"title":504,"path":848,"stem":849},"\u002Fguides\u002Fcompatibility","guides\u002Fcompatibility",{"title":851,"path":852,"stem":853},"Concurrency","\u002Fguides\u002Fconcurrency","guides\u002Fconcurrency",{"title":6,"path":841,"stem":843},{"title":856,"path":857,"stem":858},"Evaluation","\u002Fguides\u002Fevaluation","guides\u002Fevaluation",{"title":860,"path":861,"stem":862},"External readers","\u002Fguides\u002Fexternal-readers","guides\u002Fexternal-readers",{"title":864,"path":865,"stem":866},"Installation","\u002Fguides\u002Finstallation","guides\u002Finstallation",{"title":868,"path":869,"stem":870},"Logging","\u002Fguides\u002Flogging","guides\u002Flogging",{"title":872,"path":873,"stem":874},"Migrating from pkl-zig","\u002Fguides\u002Fmigration","guides\u002Fmigration",{"title":876,"path":877,"stem":878},"Ownership","\u002Fguides\u002Fownership","guides\u002Fownership",{"title":880,"path":881,"stem":882},"Projects","\u002Fguides\u002Fprojects","guides\u002Fprojects",{"title":884,"path":885,"stem":886},"Quick start","\u002Fguides\u002Fquickstart","guides\u002Fquickstart",{"title":888,"path":889,"stem":890},"Readers","\u002Fguides\u002Freaders","guides\u002Freaders",{"title":490,"path":892,"stem":893},"\u002Fguides\u002Fsecurity","guides\u002Fsecurity",1792908673514]