Automating XML Workflows with oXygen XML Developer and Ant/XSLT

Troubleshooting Common oXygen XML Developer Issues (Quick Fixes)

1. Editor won’t validate XML

• Cause: Wrong XML catalog, missing schema/DTD, or incorrect validation scenario.
• Quick fixes:
  1. Check the active validation scenario (Validate menu → Validation Scenarios) and select the correct one.
  2. Ensure the document’s xsi:schemaLocation or DOCTYPE points to an available schema/DTD.
  3. Add or update XML Catalog (Options → Preferences → XML Catalogs) to map public/system IDs to local files.

2. No autocomplete / content completion not working

• Cause: Missing associated schema/DTD, or completion settings disabled.
• Quick fixes:
  1. Associate the correct schema in the Document Type or via namespace-to-schema mappings (Options → Preferences → XML → XML Schema).
  2. Enable Content Completion (Options → Preferences → Editing → Content Completion).
  3. Reopen the file or restart oXygen to reload schemas.

3. XSLT/XQuery transformations fail

• Cause: Wrong processor, classpath issues, or wrong transformation settings.
• Quick fixes:
  1. Validate the transformation scenario (Transform → Configure Transformation Scenarios) and select the right processor (Saxon, Xalan).
  2. Check the transformation parameters and input file path.
  3. If using a custom processor JAR, ensure it’s added to the processor classpath in Preferences.

4. DITA maps not resolving topics or links broken

• Cause: Incorrect relative paths, missing map references, or catalog issues.
• Quick fixes:
  1. Verify topic paths inside the map file are correct and relative to the map’s location.
  2. Add map/topic URIs to the XML Catalog if using flattened builds or external resources.
  3. Use the “Check DITA Maps” action to list broken references.

5. Problems with publishing (PDF/HTML output incorrect)

• Cause: Missing FO processor, stylesheet errors, or resource paths wrong.
• Quick fixes:
  1. Confirm the FO processor (FOP/Antenna House) is configured in Transformation Scenarios.
  2. Check for XSL-FO errors in the transformation log and fix stylesheet issues.
  3. Ensure images and CSS referenced in the output are reachable (use absolute or correct relative URLs).

6. Slow performance on large files

• Cause: Large single-file XML, validation on every keystroke, or insufficient memory.
• Quick fixes:
  1. Disable real-time validation while editing large files (Options → Preferences → Editor → Validation).
  2. Increase JVM memory in the oXygen startup script (set -Xmx to a larger value).
  3. Split very large files into smaller modules if feasible.

7. Schema/namespace conflicts and ambiguous element resolution

• Cause: Multiple schemas for same namespace or missing namespace declarations.
• Quick fixes:
  1. Ensure correct namespace prefixes and declarations in the document.
  2. Use XML Catalog to map namespace to the intended schema.
  3. Remove or reorder conflicting schema entries in Preferences.

8. License or activation errors

• Cause: Expired license, network issues, or incorrect license file.
• Quick fixes:
  1. Verify license validity and re-enter license key (Help → License Manager).
  2. If using a floating license, check network access to the license server and firewall settings.
  3. Contact your license administrator or oXygen support with the license ID.

9. Git/Subversion integration problems

• Cause: External tool path not set or authentication issues.
• Quick fixes:
  1. Configure external VCS paths in Preferences (Version Control settings).
  2. Use credential helpers or SSH keys for authentication and ensure keys are loaded.
  3. Check file permissions and line-ending settings that may cause spurious diffs.

10. UI/editor layout or plugin issues after update

• Cause: Incompatible plugins or cached settings.
• Quick fixes:
  1. Reset perspectives or workspace (Window → Reset Perspective).
  2. Start oXygen with a clean workspace (move the workspace folder temporarily).
  3. Disable/uninstall incompatible plugins and reinstall official updates.

Diagnostic checklist (quick)

1. Reproduce the issue and capture the error message/log.
2. Check Preferences for relevant settings (validation, processors, catalogs).
3. Verify file paths, namespaces, and schema associations.
4. Restart oXygen after config changes.
5. Increase logging verbosity and consult the Transformation/Validation log for details.

If you want, I can provide exact menu paths or step-by-step instructions for any specific issue above.