Error Messages Reference

A complete catalog of the literal error and warning strings TableCrafter can display, what each one means, and the concrete step that resolves it. Every message below is taken verbatim from the v3.5.6 source so you can match what you see on screen.

TroubleshootingData SourcesExportAirtableAJAX

How TableCrafter surfaces errors

TableCrafter renders data server-side first (for SEO and a fast first paint), then hydrates with JavaScript. Because of that, the same underlying problem can appear in three different places, and the wording you see tells you which layer failed:

Admin Setup Guide — a dashed red box titled "TableCrafter Setup Guide". This only renders for users with the manage_options capability and embeds the raw technical error in a <code> tag plus troubleshooting tips.
Public error state — logged-out visitors never see the technical message. They get the friendly fallback "Unable to load data. Please check back later." inside a .tc-error-state box, or whatever you pass to the error_message attribute.
JavaScript error container — if the browser-side fetch or hydration fails, the table area is replaced with a .tc-error-container holding a .tc-error-message and a Retry button (.tc-retry-button).

ℹ️

The detailed message is intentionally hidden from non-admins. To read it, view the page while logged in as an administrator, or check the WordPress debug.log — TableCrafter calls log_error() for fetch, HTTP, and JSON failures.

Data-source errors (rendering the table)

These come from the server-side fetch-and-render pipeline. With an admin logged in they appear inside the Setup Guide box; otherwise they are swallowed into the generic public message.

Error string	Meaning	Fix
The provided URL is blocked for safety (Local/Private IP).	The `source` resolves to localhost or a private/internal IP. TableCrafter blocks these to prevent server-side request forgery (SSRF).	Point `source` at a public, internet-reachable URL. Internal hosts like `127.0.0.1`, `192.168.x.x` and `10.x.x.x` are rejected by design.
CURL Error: …	The HTTP request never completed — DNS failure, TLS handshake error, or timeout (connect 10s / total 30s). The cURL detail is appended.	Confirm the URL loads in a browser, that the host has a valid SSL certificate, and that your server can make outbound requests.
Source returned HTTP <code>	The server responded but with a non-200 status (e.g. 401, 403, 404, 500).	A 401/403 means the endpoint needs auth or is private; 404 means a wrong path; 5xx is an upstream outage. Use a public, unauthenticated URL.
The source did not return a valid JSON structure.	The body downloaded but failed `json_decode` — often an HTML error page, a redirect, or malformed JSON.	Open the URL directly and verify it returns raw JSON, not an HTML login/error page. CSV and Google Sheets URLs are handled separately and should end in `.csv` or be a Sheets link.
Empty Source: The data received is empty.	The fetch succeeded but produced no data.	Confirm the endpoint actually returns rows. If it is gated by an API key or query string, include those in the URL.
Path Error: Key '<segment>' not found in data structure.	The `root` attribute points at a key that does not exist at that nesting level.	Fix the dot-path in `root` to match the JSON exactly (it is case-sensitive). See the JSON Root example below.
Structure Error: The target data is not a list/array.	After following `root`, the value is a scalar or single object, not an array of rows.	Drill `root` down to the array that holds your rows, e.g. `data.results` rather than `data`.
Empty Dataset: No rows found at this path.	The path resolved to an array, but it is empty.	Check that the source currently has records, or that filters in the upstream query aren't excluding everything.
Rendering Error: The data structure at this level is a simple list, not a table (list of objects).	The array is a flat list of values rather than a list of objects with columns.	Point `root` at a list of objects (rows). Note: a simple list of scalars is auto-wrapped into a single "Value" column, so this error is rare.

The JSON Root path, in practice

If your API wraps rows like { "data": { "results": [ ... ] } }, set the path with the root attribute:

<!-- Reaches into data.results before building the table -->
[tablecrafter source="https://api.example.com/v1/people" root="data.results"]

A wrong segment produces Path Error: Key '<segment>' not found; pointing at the wrapping object instead of the array produces Structure Error.

Empty / unconfigured source warnings

If the source attribute is missing entirely, TableCrafter shows a placeholder instead of an error — the wording depends on context:

String	Where it appears	Fix
Configure Your Data Source / Add a JSON URL, CSV file, or Google Sheet to create your table.	Block editor and REST preview (the `.tc-placeholder` box).	Set a `source` in the block sidebar.
⚠️ TableCrafter: Please configure a data source to display your table.	Published front-end page when the block has no source (a yellow `.tc-error` box).	Edit the post and add a `source` URL to the block or shortcode.

Provide a friendly public fallback

The error_message attribute (also exposed as the Elementor widget's "Error Message" control) overrides the default "Unable to load data. Please check back later." shown to visitors when a source fails.

Attribute	Required?	Purpose
source	Required	Public JSON, CSV, or Google Sheets URL. Missing/empty triggers the placeholder.
root	Optional	Dot-path to the array of rows. Mismatches cause Path/Structure errors.
error_message	Optional	Custom text shown to non-admin visitors when the source can't load.

[tablecrafter source="https://api.example.com/data.json" root="results" error_message="Our live pricing is briefly unavailable — please refresh in a minute."]

⚠️

Note: error_message only replaces the public fallback. Administrators always see the full Setup Guide with the underlying technical reason, so you can still diagnose the problem.

AJAX proxy and permission errors

When the front-end JavaScript can't read a source directly (CORS), it routes through the tc_proxy_fetch AJAX action. These strings are returned as JSON and surface in the browser console or the .tc-error-message box, prefixed by the JS layer with "Unable to load data."

Error string	Meaning	Fix
Unauthorized: You do not have permission to fetch remote data.	The proxy requires `edit_posts` or `manage_options`; the current user has neither.	Use server-side rendering (the default) for public pages, or ensure the requesting user has editing rights.
Rate limit exceeded. Please wait before making more requests.	More than 30 proxy requests in 60 seconds from one user (HTTP 429).	Wait a minute. Reduce aggressive `auto_refresh` intervals and avoid many proxied tables on one page.
Error: No URL provided.	The proxy request arrived without a `url` parameter.	Make sure the table container has a valid `data-source` / `source` value.
TableCrafter Proxy Error: <detail>	The proxy reached the fetch layer and got one of the data-source errors above; the underlying reason is appended.	Resolve the appended message (HTTP, JSON, or security error) using the data-source table.
Proxy HTTP error! status: <code> / Proxy Error	Browser-side: the `admin-ajax.php` call itself failed or returned `success:false`.	Check that `admin-ajax.php` is reachable and not blocked by a security plugin or cache rule.

Token and nonce failures

The Airtable token-save and other admin actions return short security strings on a failed handshake:

Permission denied. / Insufficient permissions — the action needs manage_options (or read/edit_posts for exports). Log in with a capable account.
Invalid nonce — the security token expired (often a stale, cached admin page). Hard-refresh the screen and retry.
Token is required. / Encryption failed. — the Airtable Personal Access Token field was empty, or the server couldn't encrypt it. Re-enter the token; if encryption fails, verify OpenSSL is available on the host.

Airtable source errors

The Airtable connector maps Airtable's HTTP status codes to plain-language messages. These appear wherever the source fails (Setup Guide for admins, fallback for visitors).

Error string	Meaning	Fix
Airtable Base ID, Table Name, and Token are required.	One of the three required Airtable settings is blank.	Provide all three: Base ID, Table Name, and a Personal Access Token.
Invalid Airtable token. Please check your Personal Access Token.	Airtable returned 401 — the token is wrong or revoked.	Generate a fresh Personal Access Token and re-save it.
Access denied. Your token may not have access to this base/table.	Airtable returned 403 — the token lacks scope for that base.	Grant the token access to the specific base and the `data.records:read` scope.
Airtable base or table not found. Please check Base ID and Table Name.	Airtable returned 404.	Verify the Base ID (starts with `app`) and the exact Table Name.
Airtable rate limit exceeded. Please try again in a few seconds.	Airtable returned 429 — too many requests.	Wait a few seconds. Caching reduces repeat hits.
Airtable server error. Please try again later.	Airtable returned a 5xx.	Transient upstream outage — retry later.
Failed to parse Airtable response. / Invalid Airtable URL format.	The response wasn't valid JSON, or a pasted Airtable URL couldn't be parsed into Base/Table IDs.	Re-check the connection; if pasting a share URL, ensure it's a standard Airtable table URL.

Export errors (CSV / XLSX / PDF)

Exports run through one honest handler (class-tc-export-handler.php) that produces genuine CSV, XLSX (via ZipArchive), and PDF files. Failures return an error string; the UI shows the toast "Export failed".

Error string	Meaning	Fix
Unsupported export format: <format>	The requested format isn't csv, xlsx, or pdf (the alias `excel` maps to xlsx).	Use a supported format value.
Invalid data or columns provided / Invalid columns provided	The export payload had no rows or no usable column config.	Make sure the table actually has visible rows and columns before exporting.
No data available for export	Server-side export fetched the source but got nothing.	Resolve the underlying source error first, then re-export.
Could not create CSV file / Could not create Excel file / Could not create PDF file	The temp file couldn't be written.	Check that the WordPress uploads/temp directory is writable and has free disk space.
PHP ZipArchive extension is required for XLSX export	XLSX is an OOXML zip package; the `zip` PHP extension is missing.	Enable the PHP `zip` extension, or export to CSV/PDF instead.
Export not found or expired / Export file not found / Invalid export ID	The download link's transient expired or the file was cleaned up.	Re-run the export to get a fresh download link.
Data fetch failed: <detail> / Export failed: <detail>	A wrapped error from the fetch or generation step.	Resolve the appended detail using the relevant table above.

Browser console and JavaScript messages

These are logged to the console (prefixed [TableCrafter] or TableCrafter:) and rarely shown on screen. They help diagnose hydration and asset-loading issues.

Console message	Meaning	Fix
TableCrafter: Library (tablecrafter.js) not loaded.	The main script didn't load before the bootstrap ran.	Clear caching/minification plugins that may reorder or strip the script; confirm `tablecrafter.js` enqueues.
TableCrafter library not loaded. (libMissing)	Admin-screen equivalent shown in a `notice notice-error`.	Same as above; re-save permalinks/clear cache so assets enqueue.
Container element not found	The target `id` wasn't in the DOM at init.	Ensure each table has a unique `id` and isn't removed by a builder/template.
TableCrafter: Failed to parse embedded data	The server-rendered JSON blob (`.tc-initial-data`) was malformed.	Usually a cache mismatch — purge the page cache and the table's transient.
Failed to copy to clipboard. Please copy manually. (copyFailed)	The browser blocked the Clipboard API (non-HTTPS or no user gesture).	Serve the page over HTTPS; the copy must be triggered by a click.

Activation: PHP version notice

On activation under an unsupported runtime you'll see an admin notice, and the plugin halts loading:

TableCrafter Error: This plugin requires PHP 8.0 or higher. You are running PHP <version>. Please upgrade your PHP version.

Fix: upgrade the site to PHP 8.0+ (the plugin declares Requires PHP: 8.0). Most hosts expose a PHP-version switcher in the control panel.

Quick diagnostic checklist

View the page as an admin to read the full message inside the TableCrafter Setup Guide box.
Open the source URL in a browser tab — confirm it returns raw JSON/CSV (HTTP 200, no login wall).
If the data is nested, fix the root dot-path so it lands on the array of row objects.
For sources behind CORS, rely on server-side rendering or the proxy; watch for the 429 rate limit message.
For export failures, verify the PHP zip extension (XLSX) and a writable temp directory.
Clear page caches and table transients after any change so the corrected output is rebuilt.

💡

Most "won't load" reports trace back to a private/authenticated URL (HTTP 401/403) or a wrong root path. Check those two first.

Next, see data-sources.html for the full list of supported source types and URL formats, and shortcode-reference.html for every [tablecrafter] attribute including error_message and root.