GenTL XML file location errors: diagnose camera description file paths

Your GigE or USB3 camera opens, discovery works, and then acquisition fails with a parse error on a file you never created, at a drive letter you did not choose. That failure does not by itself indicate a broken camera. Check the chain that locates the GenICam description file: the producer reports a location, the consumer resolves it, and the application reads or caches the bytes. This guide walks through the failure modes in the order they occur, with tests for each, so you can tell a path problem from a file problem before you suspect hardware. It pairs with our guide on XML ZIP errors during acquisition setup, which covers damaged or truncated archives.

What happens when the description file loads

Before a camera exposes its features, the consumer must build a node map from a GenICam description file, typically a ZIP or plain XML. The description's location is advertised using a URI scheme:

• local: - the file is available through the relevant transport-layer port, commonly from the camera's storage. The URI carries the file name plus an address and length, for example local:camera.zip;1000;20000. Interpret the address and length according to the documented format rather than assuming decimal notation.
• file: - the file lives on the host's file system, for example file:///C:/genicam/camera.zip.

Descriptions can be exposed for different transport-layer modules as well as the camera. Do not assume that every failing XML file came from camera storage. Identify the module named in the error, then inspect the location supplied for that module. The file name and parser position are your first diagnostics: read them before changing anything.

Symptom: the loader asks for a file on the wrong drive

You set an environment variable to redirect where description files are read and cached, for example HARVESTERS_XML_FILE_DIR=D:\, and the log still shows Filename = 'C:///GenTLSystem.xml'. Check these possibilities:

1. The setting was not applied to the running process. Confirm that your consumer version supports the variable and read its value from inside the application. A running service or development environment may retain an earlier environment. For a controlled test, create a dedicated directory such as D:\genicam\xml, grant the application access, and set the supported variable before launching it.
2. URI-to-path conversion changed the location. An empty host is normal in a local file URI: file:///C:/genicam/camera.zip explicitly names the drive. A URI such as file:///GenTL.xml lacks that drive information, so its Windows interpretation needs checking in the actual consumer. Compare the original URI with the resolved filesystem path instead of changing slash counts blindly.

A drive root is a valid Windows path. Using a subdirectory helps isolate path-joining defects and permissions, but a root path alone does not explain why another drive was selected.

Symptom: unclosed token at a specific line

The parse error unclosed token at line N, column 0 means the parser encountered an unfinished XML token. A truncated input is one possibility, but malformed XML can produce the same symptom. Check these causes:

1. The cached file is truncated. If the consumer wrote an incomplete copy, every later parse may fail at the same position. With acquisition stopped, preserve the failing file, then refresh the relevant cache using the consumer's documented procedure. Compare the retrieved payload size with the length advertised for that same payload.
2. The bytes were changed during handling. Decoding binary data as text, applying newline conversion, or appending a null byte can damage an archive or XML document. Preserve downloaded payloads as binary data. Inspect the parser's reported location and the file ending, but do not assume that every valid XML file must end with a > byte; trailing whitespace is permitted.

Matching byte counts do not prove that a file is valid. If a complete file still fails, check archive integrity, XML encoding and supported consumer/producer versions. Obtain updates and replacement description files only from the manufacturer or its distributors. Our article on GenICam node access errors covers what happens after the node map builds but a feature is missing.

Worked example: isolating a path bug in ten minutes

Given an error like File open failed in ParseXmlFile. Filename = 'C:///GenTLInterface.xml':

1. Copy the failing name verbatim. Note the unusual slashes after the drive letter, then capture the original URI before conversion. The displayed path alone does not establish which component changed it.
2. Inspect the configured cache directory and the resolved destination for GenTLSystem.xml, GenTLInterface.xml, GenTLDevice.xml or GenTLStream.xml, as applicable. If files appear on C: when you requested D:, confirm that the setting is supported and visible to the launching process.
3. Replace the drive-root value with a dedicated directory, for example D:\genicam\xml, create it, verify access permissions, and run again.
4. If parsing now fails instead of file-open, the application has progressed to reading a file. Check its contents and size; a changed error does not by itself prove truncation.

For a hypothetical transfer, suppose the advertised payload is 20,000 bytes, but the cached archive contains 18,432 bytes. The shortfall is:

That mismatch justifies investigating retrieval or cache writing. Compare like with like: an archive of 20,000 bytes might extract to an XML document of 61,440 bytes without any error. Those are different artifacts, so their lengths need not match.

For a separate plain-XML example, an advertised length of 12,288 bytes and a saved length of 12,288 bytes rule out a simple length shortfall, not malformed content. A saved file of 0 bytes is empty and cannot provide the expected description. These are diagnostic examples, not expected sizes for a particular camera.

Each step tests one link in the chain, so the first step that changes the error message tells you where to investigate next.

What the camera side looks like

When a camera advertises a local: URI, the consumer retrieves the description through the transport layer rather than opening the source as a host file. A consumer may still cache those bytes locally, so this scheme does not rule out host-directory, permission or cache problems. Check the actual URI rather than assuming its scheme from the camera interface.

A GigE camera such as the MV-CU020-90GC carries a 1/1.7" global-shutter sensor on a C-mount; none of those characteristics determines how the consumer resolves description-file paths.

Running this reliably on a vision controller

On a dedicated machine such as a vision controller, path handling is part of deployment, not just development. The MV-VC3301H-128G66 has 8 GB of memory and 4 built-in channels for light outputs; its catalog listing includes a VM6200Pro license. Whatever machine you deploy on, keep the same rules: a fixed XML directory, environment variables set by the service or launcher rather than the user session, and no unnecessary writes to drive roots.

Choosing the right directory strategy

A dedicated directory makes the destination easier to inspect and manage. An installed application directory may be read-only, so use an application-data location when necessary. Separate writable cache files from packaged resources, and distribute description files only when their licensing permits it.

Checks before you call it a camera fault

• The URI scheme and the module supplying it are identified; local: and file: require different retrieval paths.
• The cache directory is a real, accessible directory visible to the running process.
• The cached payload's size equals the advertised byte length for that same payload, with the documented numeric format interpreted correctly.
• The archive extracts successfully, or the plain XML parses without unexpected truncation or added bytes.
• A second camera of the same model on the same host is tested. Matching failures suggest a shared configuration or software issue, but do not conclusively exclude a device-side problem.

If the node map builds but features behave oddly afterwards, continue with our guide to GenICam exposure feature discovery, and for producers that will not open at all despite appearing in discovery, see GenTL camera open failures. Deploying inside containers adds another layer of path isolation, covered in GenTL discovery in containers, and Python-specific binary issues are handled in Python 3 GenICam file access.

Prevention checklist

• [ ] Set the supported XML directory to a dedicated, writable subdirectory rather than a drive root.
• [ ] Launch the application from a shell or service where the variable is actually set.
• [ ] Log the producer's URI before resolution, on every startup.
• [ ] Validate cached payload sizes against their advertised lengths.
• [ ] Follow the documented cache-refresh procedure when updating the producer or consumer library.
• [ ] Test with two cameras before blaming hardware.

Next step

If you are specifying hardware for a GenTL-based build, start from the area scan cameras category or the camera finder, pair one with a vision controller, and use the system configurator to plan the hardware. Verify software compatibility and licensing separately. If a path problem survives every check above, our support team can help you read the producer's log; reach us through the contact page.