Troubleshooting GT Link Manager

Most GT Link Manager troubleshooting sessions end at the same place: rewrite rules. If your branded links return 404, flush permalinks first and you’ve probably fixed it. This lesson collects every failure mode I’ve seen in support, in descending order of likelihood, with the diagnosis steps for each.

Redirect URLs return 404

This is the most common issue right after installation or a site migration. It almost always means the WordPress rewrite rules haven’t been rebuilt. Saving settings rebuilds them for you after a prefix change, so a 404 after a prefix change usually means the URL still carries the old prefix.

Go to GT Links → Settings and click the Flush Permalinks button. Alternatively, go to Settings → Permalinks and click Save Changes without changing anything. Either action regenerates the rewrite cache.

If that doesn’t fix it, check that WordPress’s rewrite API is working at all. Go to Settings → Permalinks and confirm you have a non-Plain permalink structure selected. The redirect system depends on WordPress’s rewrite engine, if you’re using the Plain (?p=123) permalink structure, rewrite rules don’t function and GT Link Manager can’t work.

If you’re on a server running Nginx rather than Apache, verify that your Nginx configuration is passing requests through to WordPress correctly. Apache handles WordPress’s mod_rewrite rules automatically via .htaccess. Nginx requires an equivalent configuration block. Check your Nginx site config and confirm it includes a try_files directive pointing to index.php.

Redirect URLs work on the home page but not in a subdirectory

If WordPress is installed in a subdirectory (e.g., yoursite.com/blog/), the rewrite rules are registered relative to that path. This should work automatically.

However, if you’re using a subdirectory install where WordPress is in a subdirectory but the site serves from the root (the WordPress Address and Site Address differ in Settings → General), rewrite rules may need manual adjustment. In this case, flushing permalinks from Settings → Permalinks after confirming the correct site address is configured in WordPress settings usually resolves it.

Links redirect to the wrong URL

If a link redirects somewhere you didn’t configure, the most likely cause is a filter modifying the destination URL. Check whether any code in your theme or another plugin hooks into gtlm_redirect_url. Also check whether the link has geolocation rules, a geo-targeted link sends different countries to different URLs by design.

If you’re not using any custom filters, verify the link’s destination URL directly in GT Links → All Links. Click Edit on the link and confirm the Destination URL field contains what you expect.

Quick Edit doesn’t save

Quick Edit uses JavaScript and an AJAX request to save changes inline. If the save appears to work (the loading indicator appears) but values revert, check the browser’s developer console for a failed network request.

A failed save comes back as a normal JSON response with success: false, and the row shows Save failed. The usual cause is an expired nonce: WordPress nonces expire, so an All Links page left open for more than 24 hours can’t save. Refreshing the page generates a fresh nonce and resolves it. An empty or invalid destination URL fails the same way.

A 500 response indicates a server-side error. Enable WordPress debug logging (WP_DEBUG and WP_DEBUG_LOG in wp-config.php) and check the wp-content/debug.log file for PHP errors.

The block editor toolbar button doesn’t appear

First, confirm the block editor assets are built and present. Check that blocks/link-inserter/build/index.js exists. If it doesn’t, the block editor JavaScript hasn’t been compiled. Run bash build.sh from the plugin root to build it.

If the file exists but the button still doesn’t appear, check the browser console for JavaScript errors. A dependency conflict (a third-party plugin registering a conflicting format type, or a broken @wordpress/rich-text import) can silently prevent the format type from registering.

Also confirm you’re in a block that supports it. The GT Link button appears when a rich text block (paragraph, heading, list, etc.) is active, and in the toolbar of a Button block. It won’t appear in other blocks without rich text editing (image, video, separator, etc.).

Importing a CSV fails or imports no records

The most common CSV import issue is a malformed header row. The import process reads the first row to identify column names. If the file was exported from a spreadsheet application that added a BOM character (Byte Order Mark) at the start, or if the encoding is not UTF-8, the header row may not parse correctly.

Open the CSV in a plain text editor (not Excel) and verify the first row is a comma-separated list of column names with no leading characters.

If the import processes but reports zero imported and zero skipped, check whether the file has Windows-style line endings (\r\n). Most PHP CSV parsers handle these correctly, but some environments don’t. Convert the file to Unix line endings using a text editor or command-line tool.

If the import reports rows as skipped unexpectedly, and you’re using Skip duplicate mode, it means the slugs in the import file already exist in the database. Switch to Overwrite or Auto-suffix mode.

Geo rules don’t apply

If a geo-targeted link sends everyone to the default destination, work through the chain in order. First, confirm Country routing is on in GT Links → Settings, the per-link rules only run when the site-wide setting is enabled. Second, check the Detected Now readout in the Country-based redirects settings card. It shows which country and source resolved for the current request, and it distinguishes “nothing is proxying this site, so no country is expected” (normal on local or staging installs) from “your CDN is in front but sent no country header” (a misconfiguration, on Cloudflare enable IP Geolocation for the zone).

The Check Detection button runs a loopback self-test: it sends your site a request carrying a country header and reports what the plugin detected at the other end. If that passes, detection works and the problem is upstream (your CDN isn’t forwarding a country header).

If rules apply for new visitors but returning visitors keep landing on the wrong country’s URL, the link is using a 301. Browsers cache a 301 permanently, which pins each visitor to whichever country they were in on their first click. Switch the link to 302 and have affected visitors clear their browser cache.

For live debugging, enable the Troubleshooting setting and inspect the X-GTLM-Country response header on a geo redirect. It shows the detected country, its source, and whether a rule matched.

Database tables are missing after activation

If the plugin activates but the All Links page shows a database error, the custom tables weren’t created during activation. This can happen if the database user doesn’t have CREATE TABLE privileges.

Check your database user’s privileges. The WordPress database user needs CREATE TABLE and ALTER TABLE to allow plugin table creation via dbDelta(). Contact your host if privileges are restricted.

You can also trigger table creation manually by deactivating and reactivating the plugin. Each activation runs the table creation routine through dbDelta(), which creates the tables if they don’t exist and adjusts the schema if they do.

Redirects are slow on first hit

If the first request to a redirect URL is noticeably slower than subsequent requests, this is normal behavior when no persistent object cache is installed. The first request queries the database; subsequent requests are served from the object cache (in-memory for the request lifecycle, or from a persistent store like Redis if one is configured).

To make first-hit performance consistent with subsequent hits, install a persistent object cache plugin and configure it for your caching backend. Redis Object Cache and W3 Total Cache (Redis mode) are common choices. With a persistent cache, slug lookups are served from Redis on every request, eliminating the database query entirely.

Running the built-in diagnostics

GT Link Manager includes a diagnostics tool at GT Links → Settings. Scroll to the bottom and click Run Diagnostics. The tool checks:

Whether both database tables exist and are accessible.

Whether the rewrite rules for the current prefix are registered.

Whether a real redirect works: it sends a HEAD request to the branded URL of your newest link and reports the status code and Location header. With no links yet, it reports “No link available for runtime redirect test.”

When geolocation is enabled, the output also includes a Geolocation row showing the detected country, its source, and which country headers were present on the request.

The diagnostic output identifies which checks pass and which fail, with short descriptions of likely causes for failures. This is a good first step for any configuration issue where the root cause isn’t obvious.

The Diagnostics panel in settings automates most of these checks. If a redirect resolves but goes to the wrong place, review the link’s mode in the redirect system lesson. Standard links always resolve first, so a regex or direct link can’t override one, but it can take over a real WordPress page that shares its path.