Logging and Troubleshooting

Enabling and Disabling Logs #

The plugin includes an optional logging subsystem controlled by the option key davix_h2i_log_enabled, also represented by constant DAVIX_H2I_LOG_OPTION. The loaded troubleshooting and admin-operations documentation confirms that logging is not always on by default; it is enabled or disabled through the plugin settings.

The documented settings update path is:

• option update hook: update_option_davix_h2i_log_enabled
• callback: davix_h2i_log_option_updated()
• runtime toggle function: davix_h2i_toggle_log()

When Logging Is Enabled #

The troubleshooting guide documents these effects when logging is turned on:

• the log directory is created or hardened
• the active tokenized log file is created or truncated
• logging can then write entries into that file during runtime

The admin-operations guide adds that hardening can occur both when logging is enabled and when log writing occurs.

When Logging Is Disabled #

The troubleshooting guide says that disabling logging deletes matching davix-h2i*.log* files if present. The admin-operations guide gives a slightly more specific runtime description: disabling logging deletes the active log file if present, but does not necessarily remove the log directory or hardening files.

For public documentation, the safe source-backed takeaway is:

• enabling logs prepares the log storage and active log file
• disabling logs removes plugin log file output
• log directory cleanup is not the main runtime disable behavior and should not be relied on as a full storage reset

Where Logs Are Stored #

The log storage path is documented in the helpers and troubleshooting materials.

Log Directory #

davix_h2i_log_dir() resolves to:

• wp_upload_dir()['basedir'] . '/davix-h2i/logs'

Log File #

davix_h2i_log_path() resolves to:

• <log_dir>/davix-h2i-<token>.log

The admin-operations guide gives the same location in user-facing terms under uploads-backed storage.

Hardening Files #

The plugin also hardens the log directory by creating these files when needed:

• index.php
• .htaccess
• web.config

That hardening is part of the logging subsystem and helps explain why the log directory may remain present even after log output is disabled.

[Image placeholder — Debug Log settings section showing the logging toggle and log viewer link]

Reading Logs #

The plugin supports multiple documented log-reading paths.

REST Log Routes #

The troubleshooting guide confirms these REST endpoints:

• GET /davix-h2i/v1/logs/read
• GET /davix-h2i/v1/logs/view

These are protected by the log permission callback, which requires a valid REST nonce and manage_options.

AJAX Log Refresh and Fetch #

The plugin also supports AJAX log reading through:

• davix_h2i_refresh_logs
• davix_h2i_fetch_logs

Both are documented as mapping to davix_h2i_refresh_logs_ajax().

Standalone Admin-Post Viewer #

A standalone viewer is available through:

• action: davix_h2i_log_viewer
• callback: davix_h2i_render_log_viewer_standalone()

The plugin interface docs also note that the Debug Log tab includes an Open Log in New Tab link when logging is enabled.

Permissions for Reading Logs #

Log viewing is restricted to users with manage_options. The troubleshooting guide explicitly distinguishes log access from feature-route access, and the admin-operations guide confirms the same requirement for REST, AJAX, and admin-post log viewers.

How to Debug Safely #

The troubleshooting guide includes a dedicated safe-debugging section and a global checklist.

Turn Logging On Only When Needed #

The guide recommends enabling debug logging for incident triage and disabling it afterward if you no longer need ongoing diagnostics.

Verify the Core Access and Request Model #

The global debug checklist documents these common prerequisites:

• user has upload_files
• user has manage_options for logs
• user has edit_post for each attachment
• x_wp_nonce header is present
• nonce action is wp_rest
• API key is configured
• base URL uses HTTPS
• outbound HTTPS is allowed
• uploads and log storage are writable
• attachment file exists on disk
• H2I payload is within configured limits
• timeout and retry settings are sane

This checklist is the most reliable starting point before treating a failure as a product defect.

Use Logs Together with the Relevant Workflow Context #

Because the plugin’s workflows are spread across Image, H2I, Tools, and Auto-Optimize, the most effective troubleshooting path is:

• confirm configuration in the relevant settings tab
• confirm the current user satisfies permission requirements
• confirm attachment files exist
• review log output while reproducing the issue
• turn logs off after finishing diagnosis

Common Permission Errors #

The troubleshooting guide documents the main permission-related failures.

davix_h2i_invalid_nonce #

This error is emitted by:

• davix_h2i_rest_permissions()
• davix_h2i_log_permissions()

Documented details:

• HTTP status: 403
• cause: missing or invalid x_wp_nonce for action wp_rest
• fix: send a valid REST nonce generated with wp_create_nonce( 'wp_rest' ) for the authenticated user session

davix_h2i_forbidden_attachment #

This error is emitted when a handler checks current_user_can( 'edit_post', $attachment_id ) and the current user does not have access to one or more selected attachments. The troubleshooting guide notes that this often appears in bulk requests where one selected item is not editable by the current user.

Log Access Failures #

For logs specifically, the required capability is manage_options. If a user can use media workflows but cannot view logs, that is consistent with the documented separation between feature-route permissions and administrator-level log access.

Common Request Errors #

The plugin docs document several request and transport failure categories.

davix_h2i_transport_error #

This is used for request transport failures when the outbound HTTP request does not complete successfully. The behavior docs list it among top-level request failures for Image, H2I, and Tools flows.

davix_h2i_upstream_error #

This is used when the upstream service returns an error condition that the plugin surfaces as a top-level failure. The behavior docs list it for feature request handling, and the troubleshooting guide treats upstream failures as part of normal request diagnosis.

davix_h2i_insecure_base_url #

The request client rejects non-HTTPS base URLs. If the resolved base URL is not HTTPS, the request fails with this error. The troubleshooting checklist explicitly calls this out.

davix_h2i_disallowed_download_url #

The plugin restricts download URLs to HTTPS and the configured base host. If a returned download URL falls outside those restrictions, the request can fail with this error.

Missing File and Payload Errors #

davix_h2i_missing_file #

This error is documented across feature flows when the source attachment file cannot be found on disk. The troubleshooting guide recommends checking the attachment path resolved by get_attached_file() and confirming the file exists.

This is especially relevant for:

• Image preview and generate
• H2I attachment-context flows
• Tools analyze
• upload-time auto-optimize

davix_h2i_payload_too_large #

This is the documented H2I payload-size error. It occurs when the combined HTML and CSS content exceeds the configured H2I payload limit. The troubleshooting checklist points users to reducing HTML and CSS size or adjusting the setting within the supported range.

Customer-facing numeric details for payload size should be checked in the shared Errors and Limits page.

davix_h2i_missing_ids #

This occurs when a request does not include a usable attachment ID list. The behavior docs document it for Image and Tools request handling.

davix_h2i_missing_output_url #

This is documented in the Image workflow when preview or generate cannot find a usable output URL in the parsed result. In generate flows, missing output content can also appear as item-level failure text inside bulk results.

Workflow-Specific Troubleshooting Notes #

Image Workflow #

For Image issues, the loaded docs indicate the main things to verify are:

• selected IDs are valid
• source files exist
• chips and fields are valid for the selected operation
• preview returns usable URLs
• output mode is understood correctly, especially replace vs copy

H2I Workflow #

For H2I issues, verify:

• HTML and CSS payload size
• token use and template content
• format and output mode
• attachment permissions if media context is involved
• whether preview or generate is failing specifically

Tools Workflow #

For Tools issues, verify:

• IDs are present
• selected attachments exist and are editable
• at least one valid tool is selected
• similarity is only used with at least two images
• threshold and mode values are within documented constraints

Auto-Optimize Workflow #

For auto-optimize not triggering or not persisting, the troubleshooting guide recommends checking:

• davix_h2i_auto_optimize settings
• enabled
• apply_to_generated
• _davix_h2i_generated
• _davix_h2i_auto_optimized
• MIME type starts with image/
• source file exists on disk

Safe Debugging Checklist #

For a practical customer-facing checklist, the loaded docs support this sequence:

1. Turn on debug logging in the plugin settings.
2. Reproduce the issue from the relevant workflow: Image, H2I, Tools, or upload-time auto-optimize.
3. Confirm the current user has the required capability:
   • manage_options for logs and settings
   • upload_files for feature routes
   • edit_post for each attachment used
4. Confirm x_wp_nonce is present and valid for wp_rest.
5. Confirm the API key is saved and the base URL resolves to HTTPS.
6. Confirm uploads storage and attachment files are available on disk.
7. For H2I, confirm the HTML and CSS payload stays within the configured limits.
8. Review the logs using the Debug Log interface or standalone viewer.
9. Disable logging after you finish diagnosing the issue.

[Image placeholder — Standalone log viewer page showing recent Davix H2I log output]