Redirect URLs return 404
This is the most common issue after installation or after changing the base prefix. It almost always means the WordPress rewrite rules haven’t been flushed.
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 gt_link_manager_redirect_url.
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 403 Forbidden response from the AJAX call means the nonce verification failed. This can happen if the admin page has been open for more than 24 hours (WordPress nonces expire). Refreshing the All Links page generates a fresh nonce and resolves the issue.
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 rich text. The toolbar button only appears when a rich text block (paragraph, heading, list, etc.) is active. It won’t appear in 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.
The license won’t activate
If license activation fails with a network error, the plugin couldn’t reach gauravtiwari.org. Check that your server can make outbound HTTP requests. Some hosts block outbound HTTP from PHP by default. Confirm with your host that wp_remote_post() can reach external URLs.
If activation fails with an “invalid license” or “license limit reached” message, verify you’re entering the exact license key as provided — no extra spaces or line breaks. If the limit is reached, you need to deactivate the license on an existing site first, or purchase an additional activation.
If the status shows as valid but updates still don’t appear, go to GT Links → License and use the manual update check. Also try clearing the WordPress transients that cache update data — a plugin like WP Crontrol or WP Transient Manager can help with this.
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 test redirect actually performs a redirect (it creates a temporary test link, makes an HTTP request to the branded URL, and checks the response status).
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.