A camera can appear in discovery yet fail before its feature tree becomes available. An archive error at that point does not identify the cause: the description may be incomplete, incompatible with the selected ZIP reader, invalid after extraction, or inaccessible in its cache directory. This troubleshooting procedure is for engineers integrating camera acquisition software. You will isolate the failing layer, compare general-purpose archive handling with a supported acquisition-library loader, and collect evidence before changing software or hardware.
Identify which layer actually failed
Start with the earliest error, not the final exception displayed by the application. A wrapper may report a description-loading failure after an earlier directory-creation or file-write operation failed.
Record the acquisition-library version, transport producer, operating system, camera firmware revision, and description source. Identify whether the description came directly from the device, a manufacturer download, an application override, or a local cache.
Use this table to choose the first test. These symptoms suggest a starting point; none proves the diagnosis alone.
| First observed symptom | Likely layer | First discriminating test |
|---|---|---|
| Directory creation or file opening fails | Cache configuration or permissions | Test the documented directory under the application's actual account |
| Retrieved file is shorter than the reported payload | Transfer or cache write | Retrieve again and compare expected and actual byte counts |
| One ZIP reader rejects the file but another accepts it | Archive-reader compatibility or differing validation | Compare the same bytes with the supported description loader |
| Extraction succeeds but parsing fails | XML syntax, encoding, or wrong content | Inspect the parser's first error and the extracted payload |
| XML parses but feature construction fails | Description semantics or library support | Check supported description revisions and manufacturer guidance |
| Feature tree loads but a node is unavailable | Feature access rather than archive loading | Check node existence, availability, and access state |
If failure occurs before any description retrieval begins, use the separate procedure for camera opening failures after successful discovery. Repeatedly replacing XML files will not repair a transport connection that never opens.
Preserve the evidence and check transfer completeness
Keep a copy of the failed archive and the surrounding log before clearing anything. Record its byte count and a checksum, such as SHA-256. A checksum identifies whether two files contain the same bytes; it does not establish that either file is correct.
Then retrieve the description again through the manufacturer's documented mechanism or the acquisition library's supported workflow. Save the new result separately rather than overwriting the original evidence.
Check the following in order:
- Expected length: Compare the actual file size with a reported transfer length, when one is available. Do not compare compressed archive size with extracted XML size.
- Completed write: Confirm the writer has finished and closed the file before another process attempts to read it.
- Repeated retrieval: Compare byte counts and checksums across fresh retrievals. Changing results can indicate an unstable transfer or competing cache writes.
- Actual content: Verify that the supposed archive is not an error response, an empty file, or an unrelated document. A filename extension is not evidence of its contents.
- Integrity result: Capture any checksum or archive-integrity failure reported by the supported tools.
Identical failed downloads narrow the investigation, but do not prove compatibility is the issue. The device may consistently provide the same damaged or unsupported description.
Separate ZIP-reader compatibility from archive damage
A general-purpose ZIP reader and a camera-description loader do not necessarily accept exactly the same inputs. Their supported archive features, validation behavior, and handling of description packaging may differ.
Where the acquisition library documents support for compressed camera descriptions, test that supported loader against the same preserved bytes. If the loader retrieves data internally and cannot accept a saved file, record that limitation. You are then comparing complete loading paths, not only their ZIP readers.
Interpret the result carefully:
- Both paths reject the same archive: Investigate incomplete data, unsupported packaging, and the manufacturer's compatibility requirements. Agreement does not identify which cause applies.
- Only the general-purpose reader rejects it: A reader compatibility difference is plausible. Use the supported loader if the manufacturer or library documentation permits that workflow.
- Extraction succeeds, but loading still fails: Move to XML parsing and description validation. Successful decompression is only an intermediate result.
- A fresh retrieval succeeds while the cached copy fails: Investigate stale data, partial writes, and cache ownership before changing library versions.
A supported loader is not permission to ignore errors. Capture its diagnostics and verify that it constructs the expected feature tree. If it also rejects the description, stop trying increasingly permissive extractors and obtain a fresh, matching source.
Check the extracted XML without confusing syntax and support
Successful extraction establishes that bytes can be recovered from the archive. It does not establish that those bytes describe the connected camera correctly.
First, check the parser's earliest error. Common categories include truncated content, an encoding mismatch, malformed markup, and a document that is not XML at all. An error near the end of a document can be consistent with truncation, but its location alone is not proof.
Use a parser configured to avoid unnecessary external resource resolution. Treat downloaded descriptions as data, and do not execute scripts or unrelated files found beside them. If manual extraction is required for diagnosis, restrict output paths and extracted size rather than unpacking arbitrary content into an application directory.
Next, distinguish well-formed XML from a supported camera description. XML can be syntactically valid while using unsupported description features, missing required dependencies, or belonging to another firmware revision. Use the acquisition library's documented validation facilities where available.
Obtain replacement descriptions only from the camera, its manufacturer, or an authorized distributor. Match the exact device and firmware requirements. Do not substitute a similar camera's file or edit register definitions merely to make parsing succeed.
Once feature construction succeeds, a missing setting belongs to a different investigation. Follow GenICam node existence and feature-access diagnostics, rather than continuing to modify the archive.
Verify the cache directory in the running process
A valid archive can fail to load if the application cannot create, finish writing, or reopen its cached copy. Check the cache before assuming the file supplied by the camera is defective.
Find the cache configuration in the acquisition wrapper's documentation. If it uses an environment variable, verify the value inside the running process. A value visible in an interactive terminal may not be present in a service, scheduled task, or development environment.
Check these conditions:
- Resolved location: Prefer a documented absolute directory over a path dependent on the current working directory.
- Directory existence: Confirm required parent directories exist, or that the application is permitted to create them.
- Actual account: Test under the same identity that runs acquisition, not only your interactive account.
- Required operations: Verify creation, writing, reopening, and any documented rename or cleanup operations using a disposable test file.
- Storage state: Check available capacity, quotas, read-only mounts, and applicable security-policy logs.
- Concurrent users: Determine whether multiple processes share the same cache entry and whether that usage is supported.
If configuration is read at startup, changing the environment of a later terminal will not update an already running process. Restart the affected application or service through its normal procedure, then confirm the resolved setting again.
Do not make broad directories writable or run the whole application with elevated privileges as a permanent workaround. Grant the intended account only the access required for a dedicated, documented cache location.
For stale entries, stop the affected acquisition processes and follow the documented cache-refresh procedure. Preserve the failed entry first; do not delete unrelated configuration directories.
Work through a numerical transfer example
Consider a hypothetical description transfer whose reported archive length is 262,144 bytes. The saved file contains 196,608 bytes. Compare like-for-like archive sizes, before decompression.
The first priority is the incomplete transfer or write, not selecting a more tolerant ZIP reader. Preserve the short file, then examine retrieval completion, storage errors, and whether a reader opened the file before writing finished.
Suppose the next retrieval contains the expected number of bytes but still fails extraction. Length alone now cannot distinguish damaged content from a reader compatibility difference. Compare checksums, retain the integrity diagnostics, and test the supported description-loading path.
Finally, suppose that same file loads from a dedicated test directory but fails through the normal cache. This points toward a path, account, stale-entry, or concurrency difference. Confirm which difference matters by changing one condition at a time.
Decide whether software repair or hardware selection is appropriate
An archive-loading error is not, by itself, evidence that you need a different camera interface or sensor. Switching hardware can hide the original problem while leaving a service-account or cache defect unresolved.
Use the documented software path first when the camera remains supported and its matching description is available. If a software update is recommended, verify compatibility between the application, acquisition library, and transport producer. Change one component at a time and retain a recovery route.
For a new system, compare area scan cameras and line scan cameras according to the inspection task, not the archive exception. The camera finder helps narrow interface and imaging requirements; description-loader support still requires separate confirmation.
For an area scan candidate, review the catalog entry for LS-CMR-0053.
- Sensor format
- 1/1.7"
- Interface
- GigE
- Resolution
- 12 MP
- Shutter
- Rolling
For a line scan candidate, review the catalog entry for LS-LCM-0015.
- Interface
- GigE
- Lens mount
- M42
- Line length
- 2K
- Pixel size
- 14 μm
These are hardware selection references, not confirmed remedies for a description-loading failure. Before ordering, confirm support for the exact camera, firmware, transport producer, operating system, and application combination.
Verify recovery and prevent recurrence
A successful archive extraction is not the acceptance test. Verify the complete path from description retrieval to feature access, and then to acquisition where the setup permits it.
Use this short checklist:
- Cold start: Launch from a stopped application state, not only an already initialized development session.
- Correct identity: Repeat under the intended production service or application account.
- Description loading: Confirm the log identifies the expected device and a successful feature-tree construction.
- Read access: Read a documented, available feature without changing camera configuration.
- Acquisition: Run a controlled capture and verify that images reach the application.
- Restart behavior: Repeat after restarting the application to expose stale-cache or startup-environment differences.
- Documented refresh: Where supported, test both reuse of a valid cache and retrieval after a controlled cache refresh.
If the tree loads but the expected exposure setting is absent, continue with exposure feature discovery for missing attributes. That is a feature-model question, not proof of another ZIP failure.
For escalation, provide the original exception chain, software versions, description origin, firmware revision, byte counts, checksums, and the resolved cache location. Include the process identity and the exact comparison that changed the outcome. Remove credentials and unrelated sensitive logs before sharing evidence.
When the inspection also needs a new camera, start with the camera configuration step. For help separating a software-loading issue from a hardware requirement, send the diagnostic evidence through technical support.
Questions
Does a ZIP error always mean the camera description is corrupted?
Not necessarily. Readers can differ in supported archive features and validation behavior. Compare the preserved file with the acquisition library's documented description loader. Also check transfer completeness and integrity diagnostics. Acceptance by another reader is useful evidence, but it does not establish that the extracted description is correct or supported.
When should I use the acquisition library's description loader?
Use that path when the library documents support for the camera's compressed description format. It can avoid an unnecessary dependency on a separate archive reader. Keep error reporting enabled and verify successful feature-tree construction; decompression alone does not prove that the description matches the connected device.
How can I tell whether the cache directory is causing the failure?
A cache problem becomes more likely when identical description bytes load from a controlled location but fail through the application's normal directory. Check the resolved path, service-account access, incomplete writes, and competing processes. Preserve the failed cache entry before following the documented refresh procedure.
Can I replace the XML with a file from a similar camera?
Do not substitute descriptions merely because the cameras appear similar. Device features and register mappings can differ, and a file may depend on firmware revision. Retrieve the matching description from the camera, manufacturer, or authorized distributor, then confirm support in the acquisition library.
What evidence should I collect before requesting support?
Capture the earliest error and its surrounding messages, software and firmware versions, description source, expected and actual byte counts, checksums, and cache configuration. State which process account was used and whether the supported loader accepted the same bytes. Remove credentials and unrelated sensitive information before sharing.