Canvas Fingerprint Test: Empty Exports and Errors

A Canvas fingerprint test can fail to produce an image before there is any pixel result to compare. BotBrowser documents Canvas noise controls and --bot-noise-seed for consistent output workflows. That configuration does not establish that an export succeeded, the requested encoder was used, or an origin-clean requirement was met. A missing digest therefore needs an export state, not an immediate explanation about browser identity.

TL;DR

• data:, is a sentinel for an empty result, not an empty PNG. Zero bitmap dimensions and serialization failure can reach the same return value.
• MDN also documents data:, for dimensions beyond the implementation's Canvas size limit. The string does not identify which cause occurred.
• A non-origin-clean bitmap produces a synchronous SecurityError; that check comes before the zero-dimension check.
• An unsupported requested image type can successfully fall back to PNG. PNG output does not prove that the requested encoder worked.
• toBlob() has a different result surface: its immediate return is undefined, while its callback receives a Blob or null. Its security exception is still synchronous.

Contents

• Reading an export result
• Dimensions, cleanliness and exception order
• Requested formats and serialization work
• Comparison cases for fingerprint reports
• Minimal diagnostic record
• FAQ: Canvas fingerprint export states
• Practical conclusion

The diagram maps documented export outcomes. It is a source-derived decision aid, not a captured browser run or a detector score.

Reading an export result

The usual Canvas fingerprinting workflow separates drawing, readback, a digest and a later comparison. An export failure must be classified before a digest comparison is interpreted as an image comparison. If a checker replaces every caught exception or empty result with one false value, the displayed value has less information than the underlying API. It cannot recover the missing exception name, bitmap dimensions or requested format after those details have been discarded.

The HTML Standard defines toDataURL() as a serialization operation on the Canvas bitmap. The return is normally a data URL containing the encoded image, but the exact string data:, is also a specified result. That shortest data URL represents an empty text resource. It contains neither a PNG signature nor evidence that a nonempty image was encoded. Calling it a blank image confuses an absent encoded image with a valid image whose pixels happen to be transparent.

Input or phase	toDataURL() outcome	toBlob() outcome	What the outcome establishes
Bitmap is not origin-clean	Synchronous SecurityError	Synchronous SecurityError	The security precondition failed at export
A bitmap dimension is zero	data:,	Callback receives null	No image was serialized through that path
Serialization returns no file	data:,	Callback receives null	The encoder did not supply an image file
Requested type is unsupported, encoding succeeds	PNG data URL	PNG Blob	Fallback encoding succeeded
Requested type is supported, encoding succeeds	Image data URL	Image Blob	An encoded representation was produced

MDN adds an implementation-facing case: toDataURL() returns data:, when a dimension exceeds the maximum Canvas size. That maximum is not one portable constant. A record containing only the sentinel cannot distinguish that case from a zero dimension or a failed serializer. The next useful evidence is the actual bitmap dimensions and export phase, rather than a guessed graphics device.

The BrowserLeaks Canvas report analysis follows a particular PNG and digest path. Its visible support result is not a complete exception report. Documented export states distinguish outcomes that such a support result may collapse; they do not establish that BrowserLeaks exposes every one of them or preserves the original failure reason.

Dimensions, cleanliness and exception order

The Canvas bitmap and the element's CSS display box are different objects in the reasoning. The width and height attributes control bitmap dimensions; CSS can scale how the element is displayed. A large rectangle on a screenshot is not evidence of a large encoded bitmap. Conversely, a small displayed element may serialize many more pixels than its visible box suggests. A comparison based only on a screenshot can therefore pair different bitmap inputs while calling them the same fixture.

A zero dimension is also different from a drawing that paints nothing. A nonzero bitmap can contain transparent pixels and still serialize as an image. The data:, case concerns the absence of pixels in a dimension or failure to obtain a serialized file; it is not a test for whether the drawing looks interesting. This distinction prevents a transparent Canvas from being incorrectly grouped with a zero-sized one in a compatibility report.

The origin-clean flag is another independent input. Both export algorithms first check that flag. When it is false, they throw SecurityError before performing their later serialization steps. The order matters for a bitmap that also has another problematic property: a caught security exception cannot safely be relabeled as the zero-dimension sentinel. An application that logs only “Canvas unavailable” loses which operation actually stopped.

MDN describes the security condition in terms of a bitmap whose contents have or may have come from another origin. That is not a diagnosis of one particular image request. An exception does not reveal the complete drawing history, which resource affected the bitmap, or which response headers were present. Owned application logs can investigate those inputs, but a public fingerprint panel that shows an error label cannot infer them from the label alone.

Changing the way an element is displayed does not establish that its bitmap has become origin-clean. CSS dimensions and the security flag belong to different parts of the model. Likewise, a valid image URL in a document does not by itself prove that the image can be included in readable Canvas output. Displaying a resource and exporting pixels derived from it are different permissions and operations. A support record should preserve the export exception instead of treating successful display as proof that export must succeed.

Dimension limits require the same separation. A browser may expose the Canvas interfaces while a particular requested bitmap cannot be exported. Feature presence, context creation, drawing and serialization are separate checkpoints. A failure at the last checkpoint does not establish that the earlier interfaces were missing. No universal maximum dimension is supplied by the cited export algorithms, so a cross-platform report should retain the requested dimensions without turning one environment's limit into a browser-wide specification.

Requested formats and serialization work

The requested MIME type is an input, not a guarantee about the returned representation. The HTML serialization rules require PNG support and define PNG fallback when the requested type is unsupported. They also treat a type containing parameters as unsupported. A caller that expects JPEG cannot establish that JPEG was used merely because the method returned a nonempty string. The returned data URL's media type, or the resulting Blob type, is the relevant representation evidence.

This is important before comparing encoded values. Two exports can represent an equivalent drawing with different file formats and therefore different byte sequences. Even after the format is held constant, a digest of encoded bytes is a statement about those bytes, not a proof that two decoders would display different pixels. The general Canvas fingerprint workflow includes drawing and readback; an encoded-file comparison adds serialization choices that should not be silently attributed to the graphics surface alone.

The optional quality argument applies to formats that support lossy compression. MDN describes numeric values from 0 to 1; when the value is omitted or outside that range, the user agent uses its default quality. An out-of-range numeric value does not define a separate quality-error branch in the cited export algorithms, although dimensions, origin cleanliness or serialization can still cause export failure. A format that does not use the quality setting does not gain one merely because an argument was supplied. A request for a particular value is therefore not evidence that PNG used it or that every implementation applied an identical encoder configuration. Preserve the requested type and quality separately from the returned type so an ignored input or fallback is not mistaken for a rendering change.

Resolution metadata supplies another boundary. The export documentation describes 96dpi resolution metadata for formats that support encoding it. That is file metadata, not a measurement of the physical screen or the CSS size of the element. A value in a serialized image should not be repurposed as a display-density observation. Keeping bitmap dimensions, CSS layout and encoded metadata separate makes the comparison about the input that actually changed.

toDataURL() creates an in-memory string for the whole image. MDN warns about performance implications for large images and possible URL-length limits when that string is assigned to an image's src. The warning does not establish that an export or its later URL assignment actually failed. A report that records a missing image after assigning a very large URL needs to distinguish export from the later consumer operation; a failure to display the URL does not prove that serialization returned data:,.

toBlob() avoids that data-URL string interface, but it is not a universal success guarantee or a zero-memory operation. The standard still describes copying the bitmap and serializing it. Its immediate return is undefined; the image result arrives through a callback. Logging the immediate return as “no image” misreads the API contract even when the eventual callback supplies a valid Blob. The callback's null result is the absence of that image result, while a synchronous SecurityError occurs earlier and is a different path.

Comparison cases for fingerprint reports

Two records contain data:,, but their bitmap dimensions differ. One may have a zero dimension while the other requests an unsupported size or reaches a serialization failure. Equality of the strings establishes equality of the sentinel, not equality of a rendered fingerprint. Preserve width and height before deciding whether the cases share a cause. Without those inputs, the appropriate classification is an empty export with an unresolved cause, rather than a matching device signature.

An export succeeds as PNG after a JPEG request. The successful file is evidence that the fallback path produced PNG. It is not evidence that the JPEG encoder handled the request. Compare requested and actual types before grouping this record with JPEG results. A digest comparison across those representations answers a file-equality question and cannot, by itself, identify a difference in the original Canvas drawing.

A checker changes from a digest to a generic false label. The visible change may be downstream of an export failure, but the generic label does not identify the branch. The checker source or an owned application record must establish whether an exception was caught, a sentinel was rejected or a later image step failed. The published BrowserLeaks analysis separates its visible output from a complete failure diagnosis; that same boundary prevents attributing an unknown branch to privacy settings without evidence.

A toBlob() log records undefined, while a later callback records a file. These observations are compatible. The immediate value is not the asynchronous image result. Compare callback outcomes with callback outcomes, rather than comparing an immediate return from one API with a final image from another. The operation phase belongs beside the API name in a compatibility ticket, especially when logs from different export implementations are combined.

A CSS resize appears to fix the page, but exported dimensions are unchanged. The display result and the bitmap result answer different questions. A layout change may improve presentation without changing the bitmap that the serializer receives. Preserve both sets of dimensions if the support question concerns the visible element; retain only bitmap dimensions if it concerns serialization. This prevents a visual layout fix from being described as a changed fingerprint input when that input did not change.

A non-origin-clean export throws before an empty result is returned. The exception order is part of the evidence. A wrapper that converts the exception to a false value should record that it performed that conversion, because a later reader cannot reconstruct the synchronous exception from the false value. No raw pixels are needed to preserve this distinction: the method, phase and exception name are sufficient to keep it separate from the specified sentinel path.

Minimal diagnostic record

A useful export record names method, bitmap width and height, requestedType, actualType, outcome and phase. For a synchronous failure, it can retain exceptionName instead of image data. For toBlob(), it must distinguish the immediate call from callback completion. These fields describe the operation and its result without retaining the complete data URL, encoded image or digest. A schema defines fields an application may retain; only an actual application record can establish which branch ran.

Record field	Preserve	Do not infer from it
width, height	Bitmap dimensions supplied to export	Physical screen dimensions
requestedType, actualType	Requested and produced representation	That every requested encoder is supported
phase	Call, synchronous exception or callback completion	That an immediate undefined is a failed image
outcome	Image, sentinel, callback null or exception	A device identity or manipulation verdict
exceptionName	The observed exception class when available	The responsible cross-origin resource

If a report contains only a caught false value, record that limitation rather than filling in exceptionName from expectation. An unavailable detail is different from an observed exception. The same principle applies to dimensions: do not replace missing bitmap dimensions with the CSS box measured later. Derived fields can be useful, but they need their own labels so the support record does not silently become more precise than its evidence.

BotBrowser's Canvas documentation describes --bot-noise-canvas and --bot-noise-seed controls. Those controls belong to the pixel-output consistency question. They do not establish which representation a particular export produced or whether the bitmap passed the security precondition. Keep the launch configuration separate from the export-state record, and do not interpret unchanged settings as proof that every input to a later fingerprint check was unchanged.

The minimum record can also omit full resource URLs, account identifiers and image contents. A source revision or application build label is often enough to identify which export path the application intended to use. Where a particular resource is necessary for an owned investigation, apply the application's retention policy rather than placing its URL or pixels in a public report. The diagnostic value comes from preserving the branch, not from accumulating a reusable image signature.

FAQ: Canvas fingerprint export states

Is data:, a valid PNG with no visible drawing?

No. The standard describes an empty text resource. A nonzero Canvas bitmap containing transparent pixels is a different state and may serialize as an image. The sentinel does not contain an encoded PNG to compare.

Does data:, prove that Canvas fingerprinting is blocked?

No. Zero dimensions and serialization failure can produce that result, and MDN documents the implementation-size-limit case. The returned string alone does not establish a privacy setting or a detector's interpretation of the failure.

Can an unsupported format still return a successful image?

Yes. PNG fallback can succeed when the requested type is unsupported. Retain the actual returned representation instead of treating any nonempty image as confirmation that the requested format was used.

Does SecurityError identify the image that caused the problem?

No. It establishes the bitmap's non-origin-clean state at export. The exception does not include a complete drawing history or establish the responsible resource and response configuration.

Is the immediate undefined from toBlob() an error?

No. That is the method's documented return value. Its callback receives the image Blob or null; a synchronous security exception is separate from both the immediate return and the later callback.

Is there one maximum Canvas size for every browser?

The cited sources do not provide one portable numeric limit. Record the requested bitmap dimensions and the observed export state. Do not treat a maximum from one browser and environment as a limit shared by every implementation.

Does a matching data URL establish matching browser identity?

No. Equality can concern an encoded image or merely the empty sentinel. Neither establishes a person, a complete browser configuration or an external site's decision. The export state must be known before even a file-level comparison is meaningful.

Can a fixed noise seed explain an export error?

Not by itself. Seed controls target pixel-output consistency, whereas the documented export states depend on bitmap dimensions, origin cleanliness, representation and serialization. A seed value alone does not establish which conditions held or whether an image was exported.

Sources

• WHATWG HTML: Canvas and bitmap serialization
• MDN: HTMLCanvasElement.toDataURL
• MDN: HTMLCanvasElement.toBlob
• BotBrowser Canvas documentation

Practical conclusion

Classify the export before comparing a Canvas fingerprint result. Keep data:,, synchronous SecurityError, callback null, PNG fallback and an actual encoded image as different outcomes. Preserve bitmap dimensions and the requested versus returned representation; omit raw images when the support question does not need them. Then use the broader Canvas fingerprinting workflow and the BrowserLeaks report analysis for the distinct stages that follow a successful export.