Troubleshooting

Troubleshooting

Common issues and solutions when using Apex.

Build Issues

CMake Not Found

Error: cmake: command not found

Solution:

• macOS: brew install cmake
• Ubuntu/Debian: sudo apt-get install cmake
• Fedora: sudo dnf install cmake

Compilation Errors

Error: Compiler not found or incompatible

Solution:

• macOS: Install Xcode Command Line Tools: xcode-select --install
• Linux: Install build essentials: sudo apt-get install build-essential

Linking Errors

Error: undefined reference to apex_*

Solution:

• Ensure library is built: make in build directory
• Check library path: LD_LIBRARY_PATH (Linux) or DYLD_LIBRARY_PATH (macOS)
• Verify linking: -lapex flag is present

Runtime Issues

Table Not Rendering

Problem: Tables appear as code or plain text

Solutions:

• Ensure tables are enabled: Don't use --no-tables
• Check mode: Some modes disable tables
• Verify table syntax: Requires proper pipe alignment

Header IDs Not Generated

Problem: Headers don't have id attributes

Solutions:

• Check if IDs are disabled: Remove --no-ids flag
• Verify mode: All modes generate IDs by default
• Check manual ID syntax: May be incorrectly formatted

Math Not Rendering

Problem: Math appears as plain text

Solutions:

• Ensure math is enabled: Don't use --no-math
• Check mode: CommonMark and GFM modes disable math
• Verify MathJax/KaTeX: Apex outputs HTML, you need a math renderer

Wiki Links Not Working

Problem: Wiki links appear as plain text

Solutions:

• Enable wiki links: Use --wikilinks flag (disabled by default in all modes)
• Check syntax: [[Page]] not [Page]
• Example: apex document.md --wikilinks

File Includes Not Working

Problem: Include syntax not processed

Solutions:

• Enable includes: Use --includes flag (enabled by default in unified mode)
• Check file paths: Relative to document or use base_directory in API
• Verify syntax: <<[file.md] or {{file.md}}

Output Issues

No Output

Problem: Command produces no output

Solutions:

• Check input: Verify file exists or stdin has content
• Check errors: Run with verbose output if available
• Verify mode: Some modes may filter content

HTML Not Formatted

Problem: HTML is all on one line

Solutions:

• Use --pretty flag for formatted output
• Check if pretty printing is disabled in options

Missing Styles

Problem: Standalone document has no styling

Solutions:

• Add stylesheet: --style styles.css
• Use inline styles: Apex includes basic default styles
• Check CSS path: Ensure file exists and path is correct

Mode-Specific Issues

Feature Not Available

Problem: Syntax feature doesn't work

Solutions:

• Check mode: Feature may not be available in current mode
• Switch to unified mode: --mode unified has all features
• See Modes for feature availability

ID Format Wrong

Problem: Header IDs don't match expected format

Solutions:

• Check mode: Each mode has its own ID format
• Override format: Use --id-format in unified mode
• See Header IDs for format details

API Issues

Memory Leaks

Problem: Application memory usage grows

Solutions:

• Free all strings: Always call apex_free_string() on returned strings
• Check for NULL: Don't free NULL pointers (safe, but unnecessary)
• Reuse options: Create options once, reuse for multiple conversions

Thread Safety

Problem: Crashes or incorrect output in multi-threaded code

Solutions:

• Use separate options: Each thread needs its own apex_options
• Don't share nodes: Document nodes are not thread-safe
• See C API for thread safety details

Framework Not Found (Xcode)

Problem: Apex.framework not found at runtime

Solutions:

• Embed framework: Set to "Embed & Sign" in Xcode
• Check search paths: Verify framework search paths
• Verify architecture: Ensure framework matches app architecture

Performance Issues

Slow Conversion

Problem: Conversion takes too long

Solutions:

• Disable unused features: Turn off extensions you don't need
• Check input size: Large documents take longer
• Profile: Use profiling tools to identify bottlenecks

You can also enable Apex's built-in profiling output with environment variables: setting APEX_PROFILE=1 (or yes/true) will print per-phase timings from the core converter (e.g. metadata, citations, autolinks) to stderr, while APEX_PROFILE_PLUGINS=1 enables detailed timing for plugin execution, including a total time for each plugin phase (pre_parse and post_render) and individual timings for every discovered plugin; this is especially useful for tracking down slow external handlers or regex plugins—run commands like APEX_PROFILE_PLUGINS=1 apex --plugins input.md > /dev/null to capture just the timing lines.

High Memory Usage

Problem: Application uses too much memory

Solutions:

• Free strings promptly: Don't keep HTML strings longer than needed
• Process in chunks: For very large documents, consider splitting
• Check for leaks: Use memory profiling tools

Getting Help

If you encounter issues not covered here:

1. Check the Syntax page for correct syntax
2. Review Modes to ensure feature is available
3. See Command Line Options for flag usage
4. Check C API for programmatic issues

Related

• Installation - Build and installation issues
• Usage - Usage examples
• C API - API-specific troubleshooting