Debugging Tables

When a [tablecrafter] table shows the wrong data, an error box, or nothing at all, the cause is almost always one of four things: a bad source response, stale cache, a PHP-side fetch error, or a JavaScript hydration failure. This page walks you through isolating each one.

How rendering works (so you know where to look)

TableCrafter renders in two passes, and knowing which pass failed narrows the search instantly:

• Server pass (PHP). On first render the shortcode calls an internal fetch-and-render routine, builds the HTML table server-side, and stores it as a transient (Stale-While-Revalidate caching). If the fetch fails here, the server returns an error box instead of a table.
• Client pass (JavaScript). The output is wrapped in a <div class="tablecrafter-container" data-ssr="true">. The bundled library then hydrates that container to add search, filters, sorting, pagination, and export. If this pass fails, you get a server-rendered table with broken interactivity, or a JS error box.

Step 1: Enable WP_DEBUG to capture server-side errors

TableCrafter's internal logger is silent unless WordPress debugging is on. Add the following to wp-config.php (above the /* That's all, stop editing! */ line):

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );   // writes to wp-content/debug.log
define( 'WP_DEBUG_DISPLAY', false ); // keep errors out of the page

With WP_DEBUG true, the plugin's logger writes entries to wp-content/debug.log. Look for these prefixes:

Step 2: Read the admin error helper

If the server fetch fails, logged-in administrators (capability manage_options) see a built-in TableCrafter Setup Guide box rendered in place of the table. It is the fastest diagnostic you have because it echoes the exact upstream error and the most common causes:

• The source URL is not public or does not return JSON.
• The root (JSON root) path does not match the nesting of your data.
• The response is a single object/value rather than a list of row objects.

This helper is rendered with the class tc-admin-error-helper and is only visible to administrators. Non-admin visitors instead see a graceful tc-error-state message (or your custom text if you pass one). If you are logged out and only see "Unable to load data," log in as an admin and reload to read the real error.

Step 3: Check the source response directly

Most "broken table" reports trace back to the data source itself. Verify the raw response outside WordPress before touching plugin settings.

1. Open the source URL in a browser or with curl. Confirm it returns 200 and valid JSON (or CSV for CSV sources):

   curl -i "https://api.example.com/v1/products"

2. Confirm the shape is a list of rows. TableCrafter expects an array of objects. If your data is nested (for example under data.items), point the root attribute at it:

   [tablecrafter source="https://api.example.com/v1/products" root="data.items"]

3. Inspect the rendered container. Right-click the table, choose Inspect, and read the <div class="tablecrafter-container">. Its data-source and data-root values must match what you intended. A <script class="tc-initial-data"> block inside the container holds the JSON the server actually parsed, which is the ground truth for what data made it through.

Step 4: Purge the cache after fixing the source

Because rendering is cached, fixing your data or a bad root path will not appear until the cache clears. TableCrafter stores transients keyed by a hash of the source plus its attributes:

The cleanest purge is the bundled WP-CLI command, which deletes every TableCrafter transient and reports the count:

# Remove all TableCrafter caches
wp tablecrafter clear-cache

# Re-fetch and re-cache all tracked source URLs
wp tablecrafter warm-cache

Without CLI access, the SWR layer self-heals: a cached entry older than five minutes schedules an invisible background refresh on the next page view, and entries expire after an hour. If you also run a page cache (NitroPack, WP Rocket, Cloudflare, and similar), purge that too, since it can serve the old HTML even after the transient is gone.

Step 5: Debug the JavaScript pass with console output

If the table renders but search, sorting, filtering, or export do not work, the failure is in client-side hydration. The bundled library keeps verbose logging off by default. Turn it on in either of two ways:

• Globally, before the library runs, set the flag in the console or a small inline script:

  window.TABLECRAFTER_DEBUG = true;

• Per table, add data-debug="true" to the container element.

With debug enabled, the library prints log and warn messages prefixed [TableCrafter] as it hydrates, parses embedded data, and walks the root path. Note that errors always print regardless of the flag, so a clean console with debug off still means no fatal JS error occurred. Watch for these signals:

When a client fetch fails, the library replaces the table with a tc-error-container holding a tc-error-message and a tc-retry-button. Clicking Retry re-runs the load, which is useful for confirming whether a failure is transient.

Step 6: Verify the AJAX proxy and nonces

Client-side fetches and exports route through WordPress AJAX, not directly to your source. If the console shows fetch or permission errors, check these in the browser Network tab:

• Requests go to admin-ajax.php with action tc_proxy_fetch (data) or tc_export_data / tc_download_export (exports).
• A 0 or -1 response usually means a stale or missing nonce. The page localizes tc_proxy_nonce, tc_export_nonce, and tc_download_nonce into window.tablecrafterData; an aggressive page cache serving an old nonce is a common culprit, so purge it and reload.
• A 403 on the proxy typically means the source URL was rejected by the SSRF guard (private or localhost address).

Quick reference: symptom to fix

Disable debugging when you're done

Server logs can leak source URLs and request details into debug.log, and TABLECRAFTER_DEBUG adds console noise. After diagnosing, set WP_DEBUG back to false, remove window.TABLECRAFTER_DEBUG = true and any data-debug="true" attributes, and run one final wp tablecrafter clear-cache so production serves a clean, fresh render.

Next, see shortcode-reference.html for the full list of attributes referenced above, and caching.html for how the Stale-While-Revalidate layer and cache keys behave in production.