Quick Fixes

A Page Still Called Google Fonts and an Icon CDN After the Fonts Were Self-Hosted

The Culprit: The widget's embed code was copied from an earlier build and still carried its own links. Nobody had looked at what the page actually requested after the fonts moved, and an icon font served as "latest" from a CDN was never on any list.

The Fix: After any hosting or font change, open the browser's Network tab, filter for the outside hosts you expect to be gone (for example googleapis and jsdelivr), and remove every link that still appears. Replace a large icon font with the few icons actually used, as inline SVG or CSS masks. Then make the privacy page's third-party list match what really loads, and recheck the live page.

A Score Number Was Missing From a Report Header, and the Data Was Fine

The Culprit: The number was there. Its text color was the same near-black as the dark card behind it. The grade badge and "/ 100" label used lighter colors, so only the number vanished.

The Fix: Use the light text color for text on dark backgrounds. The takeaway: before chasing data or loading bugs for a missing value, check whether it is rendered but invisible. Select the area, or inspect the element's color against its background.

A Saved Report Button Quietly Ran a New Scan Every Time

The Culprit: The button linked to the live-scan page with the site address, not to the stored report by its ID. The live-scan page scans on load and saves a new record each time. The page that shows a stored report already existed; nothing pointed at it.

The Fix: Point the button at the stored-report page by ID and give "Re-scan" its own separate link. Check afterward that the total did not rise when opening reports, and that every row's link opens a real report.

A Before-and-After Score Comparison Can Be Wrong When the Scan Conditions Changed

The Culprit: Two things can change the number without the site changing: the scoring method itself (a measurement was fixed on a known date), and a scan that was blocked by the site's security software, which zeroes several checks and averages a different set of checks.

The Fix: Record the dates scoring changed and only show a numeric change between scans on the same method; otherwise say the scores aren't directly comparable. Detect blocked scans from the stored results and leave those checks out of the comparison. Also note that only the top few fixes are stored, so a fix that disappears may just have been pushed down the list. Word it "no longer listed", not "resolved".

A Rate Limiter Must Trust the Right End of the Forwarded-IP Header

The Culprit: The forwarded-IP header is a list. A client can write anything at the left end, and the CDN appends the real visitor address at the right end. Using the first (left) entry, or letting the framework treat every entry as trusted, means the key is attacker-controlled.

The Fix: Look at what your own site actually receives (a temporary diagnostic showing the raw header and the connection address), then key on the entry the trusted proxy wrote: the last one when there is one trusted hop. Prove it with a forged-header test against your own site: send 31 requests that each claim a different IP and confirm the 31st is still refused. Give each route its own counter, and treat IPv6 by its /64 prefix.

A Small Content Edit Deleted Half a Page’s Text and Crashed Every Completed Scan

The Culprit: The content tool was asked to update only three sections of the page's text file and was given only those three. It writes exactly what it is given, so the other eight sections (suggestions, fixes, upsell, hosting, email capture and more) were deleted. The page's code kept asking for them. Only the success path touched the missing text, so an error-path test passed.

The Fix: Restore the removed text from the last good version and confirm every wording is byte-for-byte the same. When a content tool replaces a file, always pass the complete document, then look at the diff stat afterward: if any lines were deleted that you did not mean to delete, stop. A short script that lists every content key the page code reads and confirms each one exists in the content file catches this before publishing.

A Platform Template Sync Silently Switched Off a Safety Feature That Was Already Tested

The Culprit: The hosting platform's automatic "sync upstream template files" update rewrote the server entry file and removed the lines that attached the limiter to its routes. The limiter code still existed, so a code search made it look present; it just was not connected to anything.

The Fix: Re-attach the limiter, put the connecting lines where the sync does not rewrite them, and add a test that fails if they disappear. More important, treat "it worked once" as expired: after every publish and after any automatic sync commit, repeat the live burst test (send one more request than the limit allows and confirm the refusal). Check what the live site does, not what the code appears to say.

A Privacy Page Said the Product Collected Nothing While It Saved Every Scan

The Culprit: The policy was written for an early version. The product then grew accounts, saved reports, billing, notification emails and its own cookie banner, and nobody re-read the policy against the code. The retention numbers were never backed by anything that deleted data, and a stale duplicate page stayed live because it was simply never linked.

The Fix: Audit the policy against the product with concrete questions: what is stored for signed-in and anonymous visitors, who receives emails and with what in them, which cookies and third-party scripts load, what is deleted and when, and is the policy linked where people sign up. Rewrite the policy to describe what actually happens, and only promise retention periods something enforces. Remove stale duplicate pages with permanent redirects to the one real page, add a test that the redirects stay in place, and trim data you do not need (here, visitor IP addresses in internal emails). Recheck the live site after publishing.

A Chat Widget Loaded on First Click Replayed Its Own Click and Closed Itself

The Culprit: The loader remembers a click on the launcher made before the script arrives and replays it afterward, so the visitor's first tap is not lost. The widget's own script also clicks its launcher by code when a link carries an "open chat" parameter, so the loader replayed that click too: open, then closed. The early load came from using mouseover as a trigger, which desktop browsers fire whenever the cursor merely rests over the page.

The Fix: Only remember clicks the browser marks as real user clicks (isTrusted is true), and ignore clicks made by script. Trigger on pointerdown, keydown, scroll, touchstart or wheel, plus a short idle timer, never mouseover. Test each way into the widget: first tap, scroll, keyboard, direct link, saved conversation, and the idle fallback.

Chatbot Search Answers Showed No Source Links Even Though a Search Had Run

The Culprit: The source links were built only from citations the model attaches to its own text. The newer model ran the search but attached no citations, so the code had nothing to display. The search results themselves were present in the response the whole time.

The Fix: Kept the model's own citations as the first choice, and added a fallback that uses the pages the search actually returned (up to two, de-duplicated, and limited by the tool's allowed-sites list) when no citations come back. Confirmed with a live question: the line appeared and the log filled in. The takeaway: when a feature depends on something optional in a response, build the fallback from the data that is always there.

A Deep Link With a Slightly Wrong Name Opens the Search Box, Not the Entry

The Culprit: The page matches the name exactly (ignoring capitalization) and, by design, falls back to plain search when nothing matches. That kind of graceful fallback hides typos. The names in the link list had been written from a summary of the catalog, so a few were near-misses: "Missing Title Tag" where the entry is called "Missing Title," and "HTTPS Migration" where no entry exists under that name.

The Fix: Checked every link name against the real list of entry names, corrected the misses, and removed the links that had no honest match. The takeaway: when a lookup fails quietly, nothing downstream will tell you. Verify names against the source list itself, not a summary of it, and treat "it loads" as different from "it lands on the right thing."

After an AI Model Upgrade, Chatbot Replies Came Back as One Word or Cut Off Mid-Sentence

The Culprit: The newer model has "thinking" switched on by default, and thinking tokens count against the maximum reply length. With a tight limit, the model could spend most or all of its budget thinking and return little or no visible text. Because the request itself succeeded, nothing looked like an error. The first suspect, the web search tool, turned out to be wrong; a temporary log of every non-normal response showed an ordinary success status with a "hit the token limit" stop reason and thinking blocks in the reply.

The Fix: Turned thinking off for ordinary replies (this assistant is a fast FAQ bot), raised the length limit a little because the new model counts about 30 percent more tokens for the same text, and stripped any unfinished internal tag at the end of a reply as a safety net. The takeaway: after any model change, re-read the defaults before the first test, and log the stop reason and response type before guessing at a cause.

For a Chatbot, A Tool Offered to the AI Never Got Used, and the Cause Was Two Different Things

The Culprit: Two separate causes were stacked. First, the tool is only offered when the site's own reference lookups find nothing, and those lookups check the last few messages, not just the newest one. A term mentioned earlier in the same test chat, or a test question that itself contained a reference term like "WordPress" or "Shopify," quietly switched search off for that turn. Second, once the tool really was offered, the model still skipped it while its thinking was switched off.

The Fix: Added a temporary per-turn log showing whether the tool was offered, what blocked it, and whether it was used. That immediately separated "never offered" from "offered and ignored." Then tested one question per fresh chat window, with no reference terms in it, and turned thinking on only for turns where the tool is offered. The takeaway: log the gate decision before blaming the model, and test in a clean session so earlier messages can't change the result.

Page Styles Silently Vanished Because the CSS Wasn’t Scoped

The Culprit: The pasted style block used unscoped global selectors such as body and .hero. Inside a WordPress content block, rules like those don't survive the same way they do in a standalone file. Fonts were a red herring; nothing in the stylesheet was being applied.

The Fix: Wrapped the whole page in a single uniquely named container and prefixed every CSS rule with it, so each selector only matches inside that wrapper. A bonus effect: the page can no longer bleed styles into the rest of the site, or pick up the theme's.

A Fix Applied to One Page Quietly Missed Its Siblings

The Culprit: The fix was treated as belonging to one file instead of one pattern. Pages that share an origin share their failure modes, and the documented rule for this problem existed but wasn't checked before the next paste.

The Fix: Went back and applied both fixes to the remaining pages. Practical habit: when a fix turns out to be a general rule about the platform, immediately list every other file made the same way and check them against it before shipping the next one, and read the rule back against the new file rather than relying on memory.

A Form That Reloads to the Homepage Usually Means Its Script Never Ran

The Culprit: WordPress ran the inline script through its text-formatting filter, which swaps straight quotes for curly ones. That broke the JavaScript before it could attach its submit handler. With no handler and no action attribute on the form, the browser fell back to a plain native submit, which just reloads the current page.

The Fix: Encoded the script as base64 and ran it with eval(atob(…)), which gives the filter no quote characters to rewrite. Loading the script from an external .js file avoids the same problem. The tell worth remembering: if a form "does nothing" or bounces to the homepage, check the console for a syntax error first. Don't start by suspecting the form service or its API key.

“cache: reload” Forces a Full Re-Download on Every Visit

The Culprit: { cache: 'reload' } was most likely copy-pasted between files during the original build as a workaround for an old caching bug, then never revisited once that underlying bug was fixed elsewhere.

The Fix: Removed { cache: 'reload' } from all three fetch calls, letting normal browser HTTP caching (respecting the server's own cache headers) take over. Treat any cache: 'reload' found elsewhere as a red flag worth double-checking — it almost always means a one-time workaround that outlived its reason for existing.

A Shared, Generic CSS Class Name Collided With a Site-Wide !important Rule

The Culprit: Reusing a short, generic class prefix across more than one feature meant a plugin pattern-matching on that prefix unintentionally reached a page it was never meant to affect.

The Fix: Renamed the affected page's classes to a fully page-specific prefix so no other snippet's selectors can ever reach it again, rather than trying to out-specificity the original !important rule. A second, unrelated bug (the scan form's submit button not actually wired up) was found and fixed in the same pass.

A Delivered File Had Escaped Newlines Instead of Real Line Breaks

The Culprit: Whatever generated the file wrote an escaped n string instead of an actual line-feed character — something that can look identical in a text preview but isn't.

The Fix: Confirmed with a syntax check (node -c) before trusting any generated code file is good to ship, then rewrote the file with real line breaks. Worth remembering: a file "looking right" in a chat window or preview pane doesn't guarantee its actual bytes are right — run a real syntax check on anything that will be executed.

A Highlight Effect Failed Because the JS and CSS Were Never Actually Connected

The Culprit: The JS added one class name; the CSS only ever defined a rule for a different selector, left over from an earlier, abandoned pure-CSS attempt at the same feature. Two independently reasonable-looking approaches were stacked without either side being updated to match the other.

The Fix: Once traced, the feature was removed rather than patched further, since it wasn't earning its complexity. General lesson: when debugging "my JS runs but nothing visibly changes," check whether the class name it adds and the class name any CSS rule targets are literally identical — not just similar.

Semantic HTML Check Required Three Independent Fixes

The Culprit: Bug 1: Minified HTML without spaces before attributes (`<h1class=`) slipped through the regex pattern. Bug 2: The fetcher never decompressed gzip responses, so raw binary noise was being pattern-matched. Bug 3: The body accumulation was capped at 150KB, and the real h1 sat at byte 467,365, past a massive wall of Autoptimize-inlined CSS in the head.

The Fix: All three bugs were fixed: (1) regex updated to catch any valid tag-terminator character; (2) zlib-based decompression added before text processing; (3) body accumulation cap raised to 500KB. Broader implication: this likely affected every regex-based check on any gzip-compressed site (Cloudflare, Sucuri, etc.), not an edge case.

Flowchart Completeness Isn’t Self-Maintaining

The Culprit: The CSS & Layout Issues section was added to the Error Guide with 18 complete entries. The section mapping in the flowchart was never updated, leaving it invisible to the Troubleshoot buttons.

The Fix: The flowchart's SYMPTOMS array was updated to include the new section; the affected symptom's description was broadened to match. Treat this as a template: any future new section name added to either JSON file should trigger a deliberate check for completeness in the flowchart mapping, rather than waiting for a visitor report to uncover the gap.

Stale-File Near-Miss Caught Before It Shipped

The Culprit: Assuming a local copy remains authoritative after time has passed. The live file was never consulted to check for interim updates.

The Fix: The actual current file was uploaded and diffed against the fix before accepting it as final. This surfaced both unrelated changes that would have been lost. Discipline: always diff against the live file, not a local copy that might be hours old, no matter how recent it felt when it was made.

Dictionary/Error Guide Context Matching Needed Wider Window

The Culprit: Single-message context window was too narrow for conversational troubleshooting where a user might reference something they said earlier.

The Fix: Widened the matching window to the last 4 user messages concatenated, so context carries across the conversation. Note: triage (clarifying questions) was deliberately kept at single-message scope to avoid re-triggering the same clarifying question after the user just answered it.

When You Have to Rule Out Candidates One at a Time to Find an Injection Point

The Culprit: An early assumption — "the snippet plugin was removed, so it can't be the source of anything" — turned out to be only partly true; one snippet was still active in the "removed" plugin the whole time. Re-checking it directly, rather than trusting the earlier claim, is what kept the search from permanently ruling out the real location.

The Fix: The candidate list was worked through exhaustively, with each candidate's current state directly verified rather than assumed from something said earlier in the conversation. The verification step also surfaced an unrelated, more urgent risk worth flagging on its own.

When a Tool’s Math Is Right But Its Message Isn’t

The Culprit: The calculations were accurate in both cases — file sizes and percentages were always reported correctly. The bug lived entirely in the presentation layer: the result-state logic didn't check whether output was actually smaller before calling it a win, and the suggestion logic didn't check what was already selected before recommending it.

The Fix: A distinct "no savings found" result state was added with honest framing for when output isn't smaller than input, and the suggestion logic was made aware of the currently selected format so it never recommends what's already active.

When the Diagnostic Tool Isn’t the Cause of What It Found

The Culprit: Neither tool was responsible. Both were simply exposing the same underlying failure: WordPress trying to reach its own wp-cron.php over HTTP and timing out. WP Crontrol reported it because that's the request it triggers; Query Monitor reported it because that's the request it was watching.

The Fix: A server-level cron was set up to execute WordPress's cron file directly through PHP, bypassing the unreliable HTTP self-request entirely.

/usr/local/bin/php /home/username/public_html/yoursite.com/wp-cron.php

When Different Systems Fail the Same Way, Check the Shared Layer First

The Culprit: The shared pattern mattered more than either individual endpoint: HTTP request, server waits, timeout, zero bytes received. Both were self-requests over HTTP failing identically, which pointed to a shared transport/loopback layer rather than two separate issues.

The Fix: Investigation was redirected toward the shared HTTP/loopback path rather than debugging WP-Cron and the REST API as two separate problems.

When a Change That Seems to Help Isn’t Proof It Was the Cause

The Culprit: With the firewall fully disabled, the exact same timeout still occurred. The earlier correlation — "it seemed better after I toggled the firewall" — didn't hold up under a direct, controlled test.

The Fix: The firewall was ruled out as the cause, and investigation moved on to the actual shared HTTP layer instead of continuing to suspect the firewall.

How to Read a Test Result Correctly — Success vs. Error vs. Timeout

The Culprit: "Forbidden" is fundamentally different from a timeout — it means the server received the request and applied its own authorization rules, proving the server is alive and processing correctly. A timeout with zero bytes received means the request never got a response at all. Separately, the later recurrence of the same timeout showed that one successful test only proves the endpoint was reachable at that moment, not that an intermittent problem is gone for good.

The Fix: Recognizing "Forbidden" as a working, authenticating server rather than a new failure, and treating the earlier clean test as a snapshot rather than a permanent fix — continuing to monitor rather than closing the issue out.

When Site Health Is Green But the Site Still Feels Slow

The Culprit: Site Health is a point-in-time diagnostic snapshot, not a continuous performance monitor — a site can pass its checks while a live request experiences slow server response or other transient conditions. And when TTFB accounts for most of the total request time, the bottleneck is how long the server took to start responding, not what the browser downloaded afterward — pointing at server-side processing, PHP, database queries, or caching, not image weight.

The Fix: The investigation was redirected from asset optimization to server-side response time, based on what the actual live request measured rather than what the snapshot check reported.

When a cPanel Label Isn’t an HTTP Response Header

The Culprit: In cPanel's own File Manager, that label is filesystem metadata describing the object as "a Unix directory" — nothing to do with what the live website actually sends visitors over HTTP.

The Fix: No fix was needed — the label was confirmed to be a filesystem-only artifact, not a real HTTP problem, and the investigation was closed.

Reading a Cron/Queue Display Correctly Before Calling It Broken

The Culprit: The failed action was an orphaned migration hook with no registered callback — a single stale entry, not evidence of a struggling queue. And the "vanished" event was simply a recurring event that ran and was rescheduled for its next occurrence, which is normal behavior for any recurring cron entry.

The Fix: Both were confirmed as non-issues by checking status, timing, and the next scheduled occurrence rather than treating either display change as a failure.

When Changing the Execution Path Is the Legitimate Fix

The Culprit: The workload itself was fine — WordPress's cron logic ran correctly. It was specifically the HTTP self-request path that was unreliable, which meant there was already a proven, working alternative path available.

The Fix: WP-Cron's built-in HTTP spawning was disabled, and a server-level cron job was set up to run the same cron file directly through PHP every five minutes instead.

define( 'DISABLE_WP_CRON', true );

// Server cron entry (every 5 minutes):
/usr/local/bin/php /home/username/public_html/yoursite.com/wp-cron.php

When a Test Has to Prove the Test Before It Can Prove Anything Else

The Culprit: The absence of the expected log said nothing yet about WordPress — the test mechanism itself hadn't been proven to work. Once the simpler proof confirmed the cron entry was firing, the WordPress-specific command was tested on its own and confirmed working.

The Fix: The cron entry's own execution was verified with a trivial command before trusting any conclusion about the more complex WordPress command running inside it.

/bin/echo "CRON PROOF" >> /home/username/cron-proof.txt

When Fixing One Bug Reveals a Second, Older One

The Culprit: The real conflict wasn't inside the element's own rule at all — a sitewide snippet had !important rules overriding page-level CSS for this class on every page that shared it. No amount of local tuning could win against that.

The Fix: Rather than escalating the specificity fight, the element was renamed from a shared class prefix to a page-specific one, sidestepping the conflict entirely. That fix then exposed a second, unrelated bug underneath: with layout now correct, the form's submit button stopped working because its JS handler referenced an element ID that didn't exist — a bug that had been there all along, masked by the layout bug sitting on top of it.

When It Looks Like Your Edit Broke Something (But Didn’t)

The Culprit: The grid's own layout math showed the stretching was structural, not new — in a CSS Grid row, every column's height is set by its tallest neighbor, and a long column had always been forcing shorter ones to stretch; the edit just added a visible line that made it noticeable. Separately, the site's theme applies its own global link color without !important, a known, already-documented pattern for this stack that always wins ties regardless of how a new rule is written.

The Fix: No layout bug existed to fix in the first case once confirmed structural. In the second, adding !important to the new rule matched the site's established convention for overriding that specific theme behavior.

A Host-Level Firewall Can Silently Block a Legitimate Page Save

The Culprit: A GoDaddy server-level Web Application Firewall – separate from and completely invisible to any site-level firewall plugin – blocked the save specifically because the page contained an whose id referenced "url" sitting next to a URL-shaped placeholder value. That specific combination matched a pattern the firewall treats as a potential malicious payload, even though it was entirely legitimate form markup.

The Fix: Found only through one-variable-at-a-time bisection – removing or renaming individual page elements until the save finally succeeded. Once isolated, renaming the input's id and placeholder to avoid that specific pattern fixed it. Worth remembering a host-level WAF like this exists entirely outside any WordPress security plugin, so it won't show up in that plugin's own logs at all.

Forcing cache: ‘reload’ on a fetch() Call Defeats Browser Caching on Every Visit

The Culprit: The fetch() call used { cache: 'reload' }, which explicitly forces the browser to bypass its own HTTP cache and hit the network every time, regardless of whether the file actually changed. This pattern got copy-pasted across several separate pages' data fetches – useful while actively editing that JSON during development, but left in place after launch it silently punishes every real visitor's load time for no benefit.

The Fix: Switch to the browser's default caching behavior – { cache: 'default' }, or just omit the option entirely – so returning visitors load the JSON from cache until it actually changes. Reserve cache: 'reload' for active development, never production.

// Forces a full re-download every time - fine while editing, bad live:
fetch(url, { cache: 'reload' })

// Lets the browser's own HTTP caching do its job:
fetch(url)

A CSS Element Using aspect-ratio Inside a Grid Can Collapse to Zero Width

The Culprit: An element relying on aspect-ratio to determine its height needs an actual width to calculate that height from. Inside a grid cell combined with margin: 0 auto – commonly used to center a narrower element within a wider column – the element has no explicit width to size itself against, so it collapses toward zero instead of filling the available space.

The Fix: Add an explicit width: 100% to the element. This gives aspect-ratio something concrete to calculate against, restoring the intended proportions within the grid cell.

.hero-visual {
  width: 100%; /* aspect-ratio has nothing to calculate from without this */
  aspect-ratio: 16 / 9;
  margin: 0 auto;
}

A One-Time Seed Script’s “Already Run” Check Needs an Atomic Lock, Not a Read-Then-Write

The Culprit: Checking get_option() and only calling update_option() afterward if it's not set is a classic check-then-act race condition. On a busy site, two requests can both check the flag – both find it unset – before either one has a chance to write the "done" value, so both proceed to run.

The Fix: Use add_option() as the lock instead. It's atomic – it fails silently and returns false if the option key already exists, rather than reading first – so there's no gap where two requests can both slip through.

if ( ! add_option( 'your_seed_flag', 1 ) ) {
  return; // someone already claimed this - stop immediately, no race window
}
// safe to run the one-time setup here

Client-Side fetch() Calls Should Use Relative Paths, Not Hardcoded Production URLs

The Culprit: The fetch() call had the production domain hardcoded directly into the URL. When that same script runs on a different domain, the browser now treats it as a cross-origin request to a totally different server, triggering CORS restrictions that were never a problem when the code and the data happened to share the same origin.

The Fix: Use a relative path instead of a hardcoded absolute URL. A relative path always resolves against whatever domain is actually serving the page, so the exact same code works correctly on production, staging, or anywhere else with zero changes.

// Breaks the moment this runs on any domain other than the one hardcoded:
fetch('https://example.com/data.json')

// Always resolves against whatever domain is actually serving the page:
fetch('/data.json')

A WPCode “Run Everywhere” Snippet Can Silently Block Another Snippet’s Shortcode Registration

The Culprit: Confirmed directly by WPCode's own support team as a real platform-level bug: certain "Run Everywhere" PHP snippets can interfere with the combined execution of other snippets, preventing later-registered hooks like add_shortcode() from ever firing. This was the actual cause of a months-long, previously unresolved "reactivating a fully-fixed file still breaks the site" mystery on this exact site – found only after extensive bisection eventually pointed at snippet interference itself, not any single snippet's own code.

The Fix: Two working fixes. Quick workaround: set the affected snippet's priority to 1 in WPCode's own settings. The permanent fix: convert the snippet to a standalone WordPress plugin file (a simple zip with a proper plugin header) instead of running it through WPCode at all – this removed the interference entirely once tested.

<?php
/**
 * Plugin Name: Your Snippet Name
 * Description: Converted from a WPCode snippet to sidestep
 * Run-Everywhere execution-order interference with other snippets.
 * Version: 1.0
 */

// paste the snippet's existing code below, unchanged

Writing About a Security Block Can Itself Get Blocked

The Culprit: A batch of debugging notes describing a previous incident (a hosting security layer rejecting a save based on field naming) failed to save — with the exact same "invalid response" symptom as the original bug it was documenting.

The Fix: The content itself was flagged, not any code in it — words like "firewall," "WAF," "403," and "blocked," clustered together, matched the same kind of pattern a security layer watches for in genuinely malicious payloads, since the vocabulary overlaps with both an honest bug report and an actual exploit description. Rewriting the same lesson with softer, more generic wording ("security software," "rejected," "a security layer") preserved the content while no longer matching the trigger pattern. When documenting a security-related bug, expect the documentation itself to sometimes hit the same wall the bug did.

Two Independently-Valid PHP Snippets Can Silently Block Each Other’s Registration

The Culprit: Both snippets passed php -l individually and executed cleanly through a full WordPress-function-stub test in isolation. No PHP error appeared anywhere – not the server's own error log, not the code-snippet plugin's internal error log. The failure only showed up as the shortcode tag rendering as literal unprocessed text on the page.

The Fix: Systematic bisection was the only thing that actually worked: deactivating every other active snippet one at a time (ruling out content, size, and execution order along the way) eventually proved the interference was specific to how the snippet-management plugin combines multiple "Run Everywhere" PHP snippets into one execution context – not a bug in either snippet's own code. The practical fix was converting both snippets into standalone plugin files instead, which fully resolved it. When two provably-correct pieces of code fail only in combination and never independently, suspect the platform combining them, not either piece itself.

Update: the plugin/support team confirmed the general mechanism – all active "Run Everywhere" PHP snippets are combined into one execution block, run in priority-then-creation order – but attributed the specific failure to a pattern (a top-level return, a trailing closing tag, or an unclosed comment) that turned out not to actually be present in the offending snippet's source after a careful re-check. Setting the new snippet's Priority to 1, forcing it to run before the older one, resolved the conflict directly – confirming priority ordering as a working lever even though the exact root cause of the original failure remains unconfirmed. If a future "Run Everywhere" PHP snippet doesn't register for no visible reason, try lowering its Priority before assuming a deeper problem.

A URL-Shaped Field Name Can Get a Legitimate Form Rejected on Save

The Culprit: An with an id referencing "url" and a placeholder that looked like a website address was enough to trigger the rejection. The exact same markup, already saved elsewhere on the site, worked fine – only a fresh save of that content failed.

The Fix: Bisecting the markup itself, one attribute at a time, isolated it to the specific combination of a URL-referencing id plus a URL-shaped placeholder value – a naming pattern that a hosting provider's own server-level security layer was reacting to before the request ever reached WordPress. Renaming the id and softening the placeholder text, with no other change, resolved it immediately. Hosting-level security software can reject a save based on field naming, not just field type or actual content.

Hardcoded Absolute URLs Break Cross-Origin Testing on Staging

The Culprit: The script's fetch URL was hardcoded to the production domain rather than a relative path, making it a genuine cross-origin request once loaded from staging – confirmed directly via a CORS error in the browser console.

The Fix: Changing the hardcoded absolute URL to a relative path let the browser resolve it to whichever domain is actually serving the page – same-origin on both staging and production, no CORS involved on either. This is a strictly better pattern than the original, not just a staging workaround.

// Wrong — hardcoded absolute URL, breaks on any other domain:
var ERRORS_URL = 'https://zu2b.com/zu2b-web-error-guide.json';

// Right — relative path, resolves to whichever domain serves the page:
var ERRORS_URL = '/zu2b-web-error-guide.json';

A Security Dashboard’s Activity Log Can Lag a Full Day Behind Real Time

The Culprit: The log's date picker couldn't even select the current day, only showing entries through the previous day – the dashboard's historical reporting view is built for later review, not real-time confirmation, and simply hadn't caught up yet.

The Fix: Most security dashboards that separate historical reporting from a live view have a separate live-activity tab – check for that specifically when debugging something that just happened, rather than trusting the historical log to reflect events from the current day.

Bisect to an Empty Baseline Before Trusting Any Single Theory

The Culprit: Reasoning about what code "looks like" it might be responsible for a bug is a weaker signal than actually testing it – several confident-sounding explanations (a specific function call, a naming collision, an execution-order issue) were each individually ruled out once tested directly.

The Fix: Reducing the suspect code down to the smallest possible non-functional stub, confirming that baseline works, then adding pieces back one at a time until it breaks again pinpoints the exact cause directly, rather than guessing based on appearance.

After a Site Restore, Several Unrelated Settings Can Silently Revert

The Culprit: A morning site restore fixed the immediate problem it was meant to fix, but also silently reverted several unrelated things: the Reading Settings homepage selection (causing a 404), a WPCode mu-plugins-style toggle-back, and a Sucuri hosting-IP entry pausing — none of which threw an obvious error pointing back to "the restore did this."

The Fix: After any full-site restore, explicitly re-check Settings → Reading (homepage/posts page), any security plugin's IP/origin configuration, and recently-active third-party integrations — rather than assuming a restore only touches the specific thing it was run to fix.

When Chasing “Everything Feels Slow,” Isolate the Narrow Symptom First

The Culprit: A REST API timeout got initially treated as a general "site is slow" problem, prompting checks across Action Scheduler queues, cron events, file permissions, and caching settings — most of which came back clean and cost real time to rule out.

The Fix: The single most useful step was deactivating plugins one at a time and re-checking Site Health after each, which isolated the failure to one specific plugin's one specific REST endpoint (real-queue/v1/jobs). That turned a vague complaint into a concrete, researchable error. When general slowness and a specific error coexist, isolate the specific error first — the general feeling of slowness is often just a symptom of that one narrow cause, not a separate problem to solve on its own.

Match Type Matters: “Matches” vs. “Begins With” in WAF URL Allowlist Rules

The Culprit: An allowlist rule for /wp-json/ saved successfully under "Matches" mode but had zero measurable effect — because "Matches" requires an exact, full-path match, while real REST requests hit longer sub-paths (e.g. /wp-json/wp/v2/types/post?context=edit).

The Fix: Switching the match type to "Begins with" made the rule cover everything under /wp-json/, not just the bare path. URL-path rules in most WAF/CDN tools offer distinct match modes (Matches/Exact, Begins With, Contains, Ends With) — a rule that saves cleanly can still be functionally inert if the match type doesn't fit the actual request shape.

An Intermittent REST API Timeout Can Point to a Correct Rule That Hasn’t Actually Applied Yet

The Culprit: Site Health's REST API check (cURL error 28: Operation timed out) kept flapping between clear and broken over several hours — even after adding a Sucuri WAF allowlist rule for /wp-json/. The rule saved without error and looked correct, but the timeout kept returning on its own unpredictable schedule.

The Fix: The rule itself wasn't wrong — it just hadn't been picked up cleanly by the firewall's rule engine. Toggling Sucuri's firewall off, then back on, forced a full rule reload, and the timeout stopped recurring afterward. A saved WAF/CDN rule isn't guaranteed to be "live" the instant it's saved; if a fix looks correct on paper but the symptom keeps intermittently returning, cycling the security layer off and on is worth trying before concluding the rule itself is wrong.

Make a Button Wider

The Culprit: A button's width defaults to fitting its own label and padding, which can look narrow or unbalanced next to other elements on the page.

The Fix: Set the button to a specific, larger width instead of relying on its own natural size.

.my-button {
  width: 220px;
}

Make a Button Narrower

The Culprit: A button sized for its longest possible label can look oversized once shorter text is used, or inside a tighter layout.

The Fix: Set the button to a specific, smaller width.

.my-button {
  width: 160px;
}

Make a Button Taller

The Culprit: A button's height is only as tall as its text and default padding require, which can look cramped next to more generously spaced elements.

The Fix: Increase the vertical padding to add height without changing the button's width.

.my-button {
  padding-top: 14px;
  padding-bottom: 14px;
}

Make a Button Shorter

The Culprit: A button with generous default padding can look oversized in a compact layout, like a form or a tight card.

The Fix: Reduce the vertical padding to make the button shorter.

.my-button {
  padding-top: 8px;
  padding-bottom: 8px;
}

Remove a Button’s Rounded Corners

The Culprit: N/A – this is a deliberate style choice, not something to fix.

The Fix: Square off the button's corners entirely.

.my-button {
  border-radius: 0;
}

Round Only the Top Corners of an Element

The Culprit: N/A – this is a deliberate style choice, not something to fix.

The Fix: Round just the top two corners, leaving the bottom edge square. The four values go top-left, top-right, bottom-right, bottom-left, in that order.

.my-element {
  border-radius: 16px 16px 0 0;
}

Round Only the Bottom Corners of an Element

The Culprit: N/A – this is a deliberate style choice, not something to fix.

The Fix: Round just the bottom two corners, leaving the top edge square.

.my-element {
  border-radius: 0 0 16px 16px;
}

Round Just One Corner of an Element

The Culprit: N/A – this is a deliberate style choice, not something to fix.

The Fix: Target a single corner directly, rather than using the four-value shorthand for one change.

.my-element {
  border-top-left-radius: 16px;
}

Make a Border Thicker

The Culprit: A default 1px border can look too thin to register as an intentional design element, especially at larger sizes.

The Fix: Increase the border's width while keeping its color and style unchanged.

.my-element {
  border-width: 2px;
}

Scale an Element Up or Down Slightly

The Culprit: N/A – this is a deliberate style choice, not something to fix.

The Fix: Scale the element larger or smaller than its natural size – a value above 1 scales up, below 1 scales down. This changes only the visual size, not the space the element takes up in the layout, so it can overlap neighboring elements if scaled too far.

.my-element {
  transform: scale(1.05); /* use scale(0.95) to shrink instead */
}

Change Text Size Directly

The Culprit: N/A – this is a deliberate style choice, not something to fix.

The Fix: Set the font size to a specific pixel value rather than relying on a default or inherited size.

.my-element {
  font-size: 20px; /* use a smaller value like 16px to reduce it */
}

Move an Element Sideways

The Culprit: A small horizontal positioning correction is needed, but changing margin or padding would shift other elements around it too.

The Fix: Shift the element left or right visually without affecting the normal document flow around it. A negative value moves left, a positive value moves right.

.my-element {
  transform: translateX(-10px); /* use a positive value to move right instead */
}

Move an Element Down

The Culprit: A small vertical positioning correction is needed, but changing margin or padding would shift other elements around it too. This is the downward counterpart to Move an Element Slightly.

The Fix: Shift the element down visually without affecting the normal document flow around it.

.my-element {
  transform: translateY(5px);
}

Keep an Image From Stretching to Fill Its Frame

The Culprit: object-fit: cover crops an image to fill its container, which isn't always what's wanted if the full image needs to stay visible.

The Fix: Let the image scale to fit within its container without cropping, adding empty space on the shorter side instead.

.my-image {
  object-fit: contain;
}

Center Content Vertically

The Culprit: Vertical centering isn't straightforward with normal block layout – content just sits at the top of its container by default.

The Fix: Turn the container into a flex container and center its content along the vertical axis. Depends on the container having a defined height; one that only sizes to fit its own content will show no visible change.

.my-element {
  display: flex;
  align-items: center;
}

Center Content Horizontally

The Culprit: Content doesn't center itself by default on either axis without deliberate layout instructions.

The Fix: Turn the container into a flex container and center its content along the horizontal axis.

.my-element {
  display: flex;
  justify-content: center;
}

Center Content Both Ways

The Culprit: Centering an element on only one axis leaves it aligned to the default edge on the other.

The Fix: Combine both properties to center the content vertically and horizontally at once. Same container-height dependency as vertical centering alone.

.my-element {
  display: flex;
  align-items: center;
  justify-content: center;
}

Adjust an Element’s Opacity

The Culprit: N/A – this is a deliberate style choice, not something to fix.

The Fix: Set a value between 0 and 1 to make the element partially see-through. Lower values are more transparent, higher values are closer to fully visible.

.my-element {
  opacity: 0.7; /* move closer to 1 for more visible, closer to 0 for more transparent */
}

Remove a Shadow

The Culprit: N/A – this is a deliberate style choice, not something to fix.

The Fix: Remove an existing shadow entirely.

.my-element {
  box-shadow: none;
}

When Every Error-Reporting Layer Stays Silent, Trace Execution With Direct File Writes

The Culprit: debug.log, the server-level error log, WPCode's own fatal-error auto-deactivation, a custom register_shutdown_function fatal catcher, and a custom set_error_handler catching every warning and notice all came back completely empty, despite the bug being fully and repeatedly reproducible. Whatever was happening wasn't a standard PHP fatal, warning, or notice that any of these layers are built to see.

The Fix: Bypass every error-reporting layer entirely and trace execution by hand: drop plain, unconditional markers directly into the code with file_put_contents(), writing to a plain text file outside any logging system. Compare which markers do and don't appear across test runs to pinpoint exactly how far execution gets before something goes wrong – this was the only method all session that produced any real signal.

function zfn_debug_mark( $label ) {
  file_put_contents(
    WP_CONTENT_DIR . '/uploads/your-debug.log',
    date('c') . " - $labeln",
    FILE_APPEND
  );
}
zfn_debug_mark( 'reached this point' );

A Clean init Hook Doesn’t Prove a Custom Post Type’s Admin Menu Will Appear

The Culprit: register_post_type() is commonly called on init, but WordPress builds the actual admin sidebar menu on a separate, later hook called admin_menu. A clean marker on init only proves the post type object itself registered – it says nothing about whether the later menu-building step actually succeeded. Trusting an init-only marker as proof the menu would appear cost a full round of false-negative testing before this was caught.

The Fix: When testing whether something admin-menu-related is actually working, add a diagnostic marker directly on admin_menu itself (a late priority like 999 ensures it runs after everything else on that hook) – test the specific hook that governs the real behavior in question, not just the nearest hook that happens to be convenient to log.

add_action( 'admin_menu', function() {
  // confirms the menu-building step itself actually ran
  zfn_debug_mark( 'admin_menu fired' );
}, 999 );

Keyword Auto-Linking Needs Word-Boundary Matching, Not Plain Substring Search

The Culprit: A plain substring search (JavaScript's indexOf, or an equivalent) matches a short term anywhere it appears as a sequence of characters, even mid-word. Confirmed directly: a dictionary term "URL" matched inside the unrelated word "curly," and "DOM" matched inside "domain" – both false positives from treating any character match as a hit, with no awareness of word boundaries.

The Fix: Match only whole-word occurrences using a word-boundary-anchored regular expression instead of plain substring search.

// Wrong — plain substring search, matches mid-word:
text.toLowerCase().indexOf(term.toLowerCase())

// Right — word-boundary regex, whole-word matches only:
var re = new RegExp("b" + term + "b", "i");
var match = re.exec(text);

Sorting a WordPress Admin Column by Meta Value Can Silently Exclude Unset Posts

The Culprit: Sorting a WP_Query by meta_key plus orderby: meta_value (or meta_value_num) uses an inner join on the postmeta table. Any post that doesn't have that meta key at all gets silently excluded from the result set – not sorted to one end, removed entirely. This happened twice independently on the same site: once for an existing Stage column, once for a brand-new column, both with the identical structural flaw.

The Fix: Add an explicit meta_query with an OR relation combining an EXISTS clause and a NOT EXISTS clause for the same key. This is WordPress's own documented pattern for keeping every post in the result set regardless of whether it has a value to sort by yet.

$query->set( 'meta_key', 'your_meta_key' );
$query->set( 'orderby', 'meta_value' ); // or meta_value_num

$query->set( 'meta_query', array(
  'relation' => 'OR',
  array( 'key' => 'your_meta_key', 'compare' => 'EXISTS' ),
  array( 'key' => 'your_meta_key', 'compare' => 'NOT EXISTS' ),
) );

A Snippet Calling a Function From Another Snippet Needs a function_exists Guard

The Culprit: One snippet calling a function defined in a separate snippet creates a hard, unguarded dependency. If the other snippet is ever deactivated, temporarily emptied for testing, or simply fails to load first, the calling snippet throws a fatal error the instant that function gets called – confirmed directly via a real error log entry, not a hypothetical.

The Fix: Wrap any cross-snippet function call in a function_exists() check. If the function isn't available for any reason, the page simply renders without that piece instead of crashing outright.

if ( function_exists( 'your_external_function' ) ) {
  echo your_external_function( $some_argument );
}

When a Bug’s Cause Is Unclear Across Several Recently-Changed Files, Isolate One at a Time

The Culprit: Code that looks structurally correct on review can still hide the actual cause, especially when several plausible suspects exist at once. Two fix attempts based on code review alone both missed the real cause in a recent case, before a more disciplined test finally isolated it.

The Fix: Reduce one file to completely empty (or comment out whole sections) while holding everything else constant, then retest. If the bug persists with that file doing nothing at all, its cause is proven to be somewhere else entirely – a definitive result from one round of testing, rather than another guess.

When a Snippet Search Comes Up Empty, the Content Might Not Be in a Snippet at All

The Culprit: Content pasted directly into page content (a Custom HTML block, for instance) lives in the WordPress database itself, not in any code snippet – so a snippet-only search, or even a plugin built specifically for search-and-replace, can come back completely empty while the real matches sit untouched in the pages table.

The Fix: Search the WordPress database directly – via phpMyAdmin's own search tab, or a direct SQL query against the posts table – rather than trusting a snippet-only tool to have covered every possible location content could live.

SELECT ID, post_title, post_type, post_status
FROM wp_posts
WHERE post_content LIKE '%your-search-text%'
AND post_status = 'publish'
AND post_type IN ('page', 'post')

Style Button Hover Transitions

The Culprit: A button with no transition property changes state instantly, which reads as stiff and unpolished rather than intentional.

The Fix: Add a smooth transition on the properties that change, then define what the hover state actually shifts to – here, a slight lift.

.my-button {
  transition: background-color 0.2s ease, transform 0.2s ease;
}
.my-button:hover {
  transform: translateY(-2px);
}

Place Two Images Side by Side

The Culprit: Image elements are block-level by default, so with no layout instruction they simply stack one on top of the other.

The Fix: Wrap the images in a flex container so they line up horizontally, with controlled spacing between them. Depends on the surrounding markup already grouping the images inside a shared wrapper.

.image-row {
  display: flex;
  gap: 16px;
}
.image-row img {
  width: 50%;
  height: auto;
}

Change the Color of a Specific Word or Phrase

The Culprit: A CSS color rule applies to an entire element uniformly – there's no way to target a single word inside a heading without first isolating it in its own element.

The Fix: Wrap just the one word in an inline span, then target that span's color independently of the rest of the heading.

<h2>Build your site <span class="highlight-word">faster</span></h2>

.highlight-word {
  color: #0DC0B3;
}

Style Custom Scrollbars

The Culprit: A default browser scrollbar is plain gray and doesn't match a custom dark or brand-colored theme.

The Fix: Set a slim, themed scrollbar for modern browsers. This covers Firefox directly – Chrome and Safari need additional ::-webkit-scrollbar pseudo-elements for the same effect, since they don't support this shorthand.

.scroll-container {
  scrollbar-width: thin;
  scrollbar-color: #0DC0B3 #0B0C10;
}

⚠️ Firefox only; Chrome/Safari need ::-webkit-scrollbar too

Create a Simple Pure-CSS Arrow Icon

The Culprit: Loading an icon font or an image for a single small arrow adds an extra network request and file weight for something CSS can draw directly.

The Fix: Build the arrow from two rotated borders. It automatically inherits the surrounding text color via currentColor, so it stays in sync with whatever element it sits inside.

.arrow-right {
  display: inline-block;
  width: 8px;
  height: 8px;
  border-top: 2px solid currentColor;
  border-right: 2px solid currentColor;
  transform: rotate(45deg);
  margin-left: 6px;
}

Add a Subtle Hover Lift to a Card

The Culprit: A static card with no hover feedback can feel flat, even when it's actually clickable.

The Fix: Combine a small upward shift with a slightly stronger shadow on hover, giving an instant tactile sense that the card is interactive.

.my-card {
  transition: transform 0.2s ease, box-shadow 0.2s ease;
}
.my-card:hover {
  transform: translateY(-4px);
  box-shadow: 0 12px 32px rgba(0, 0, 0, 0.25);
}

Break an Element Out to Full Screen-Width

The Culprit: A section inherits its parent container's max-width, so it can't reach the real viewport edges on its own, however wide the parent lets it grow.

The Fix: This exact technique is also the confirmed cause of a real horizontal-scrollbar bug on pages that don't account for it – the negative margins can make the element measure slightly wider than the true viewport. Pairing this with body { overflow-x: hidden; } is often necessary (see "Prevent Horizontal Scrolling"), and applying it once to a single top-level wrapper – rather than separately per section – avoids a related centering bug (see "Wrap a Whole Page Once for Full-Bleed, Not Per-Section").

.full-width-breakout {
  width: 100vw;
  position: relative;
  left: 50%;
  right: 50%;
  margin-left: -50vw;
  margin-right: -50vw;
}

Responsive Mobile Spacing Adjustment

The Culprit: A padding value chosen for a wide desktop layout doesn't automatically scale down for a much narrower mobile viewport.

The Fix: Reduce the padding specifically at mobile widths. This site's own standard mobile breakpoint is 600px, used consistently across every page – matching it avoids one component behaving differently from everything else.

.my-section {
  padding: 60px 20px;
}
@media (max-width: 600px) {
  .my-section {
    padding: 30px 15px;
  }
}

A CSS Grid Item Won’t Shrink Below Its Content’s Natural Size

The Culprit: CSS Grid items default to min-width: auto, meaning a grid item won't shrink below its own content's natural minimum width – even a single card elsewhere in the same grid with a wide, unbreakable string (a long code block, an unbroken URL) can force the shared column wider for every card in that grid, not just the one that contains it.

The Fix: Explicitly override the default by setting min-width: 0 directly on the grid item. This allows it to shrink as intended and rely on internal wrapping or scrolling, instead of silently inheriting a sibling's content-driven minimum width.

.grid-item {
  min-width: 0;
}

Wrap a Whole Page Once for Full-Bleed, Not Per-Section

The Culprit: Applying the full-bleed 100vw technique separately to individual sections (rather than once, to a single top-level wrapper) leaves other sections centering relative to their own inconsistent container instead of the true viewport, producing a small, hard-to-trace horizontal offset.

The Fix: Wrap the page's entire content in one single element and apply the full-bleed technique there, once. Let everything else inside center normally relative to that one correctly-anchored wrapper, rather than each section doing its own separate breakout.

.page-wrap {
  width: 100vw;
  position: relative;
  left: 50%;
  right: 50%;
  margin-left: -50vw;
  margin-right: -50vw;
}

Replace Deprecated mb_convert_encoding HTML-ENTITIES Calls

The Culprit: mb_convert_encoding() with 'HTML-ENTITIES' as the target encoding was deprecated in PHP 8.2. Any server that upgrades its own PHP version will start logging this notice on unchanged code that previously ran silently.

The Fix: Replace it with mb_encode_numericentity(), which does the same job – converting non-ASCII characters to numeric HTML entities – without triggering the deprecation. Avoid htmlspecialchars() as a substitute here if the content contains real HTML tags you still need parsed afterward, since it would escape those tags too.

$convmap = array(0x80, 0x10FFFF, 0, 0xFFFFFF);
$safe_content = mb_encode_numericentity($content, $convmap, 'UTF-8');

Old, Unchanged Code Suddenly Erroring Means Check the Server First

The Culprit: It's tempting to assume you broke something, but unchanged code can't spontaneously introduce a new bug on its own.

The Fix: Check whether anything changed on the server side instead – most commonly a PHP version upgrade performed by the host. Compare the snippet's last-edited date against when the error first appeared; a real gap between the two is the clearest signal the cause is environmental, not code-side.

A Feature Split Across PHP and CSS Can Go Silently Half-Styled

The Culprit: When a single feature's markup and its styling live in two separate files or snippets, updating one without the other leaves the new markup with zero matching styles – and because nothing throws an error, this can go unnoticed for a long time.

The Fix: Whenever a feature's HTML or PHP output changes, treat its matching CSS as part of the same change, not a separate task – check both together, especially after adding a new element type or changing how something filters or displays.

Make an Element Sit Above Another Element

The Culprit: Overlapping elements stack in an order the browser determines on its own, which isn't always the order you want.

The Fix: Raise the element's stacking order above its sibling. Behavior depends on the surrounding stacking contexts – z-index alone doesn't always work as expected if a parent element establishes its own separate stacking context.

.my-element {
  position: relative;
  z-index: 2;
}

Background Image With Adjustable Opacity

The Culprit: Setting opacity directly on a section fades everything inside it, including the text and content, not just the background.

The Fix: Create a separate image layer using a pseudo-element, so its opacity can be controlled independently of the real content.

.example {
  position: relative;
  isolation: isolate;
}
.example::before {
  content: "";
  position: absolute;
  inset: 0;
  background-image: url("IMAGE-URL-HERE");
  background-size: cover;
  background-position: center;
  background-repeat: no-repeat;
  opacity: 0.25;
  z-index: -1;
}

Set a Minimum Hero Height

The Culprit: A fixed height can clip content that ends up taller than expected; no height at all can make a section feel too short with little content.

The Fix: Set a minimum height that the section will never go below, while allowing it to expand naturally if content requires more room.

.my-hero {
  min-height: 520px;
}

Position Media Consistently

The Culprit: Media doesn't always crop or center the way you'd want by default, especially across different aspect ratios.

The Fix: Make the media cover its container fully and keep the focal position centered. This alone does not fix a video loop jumping at its restart point – that's a footage/frame issue, not a CSS positioning one.

.my-media {
  object-fit: cover;
  object-position: center;
}

Create a Reusable CSS Class

The Culprit: Styling each element individually means the same change has to be made in many places every time it's adjusted.

The Fix: Define a reusable class once, then assign it to any block or element that needs the same treatment – in WordPress, this is typically added under a block's Advanced -> Additional CSS Class(es) setting.

.quick-fix {
  /* styles go here */
}

Use a Pseudo-Element as a Visual Layer

The Culprit: Adding a real extra div just for a visual effect adds markup that has nothing to do with the actual content.

The Fix: Create a pseudo-element that can serve as an overlay, decorative layer, gradient, or other visual effect – the same underlying technique behind the adjustable-opacity background fix above.

.example::before {
  content: "";
  position: absolute;
  inset: 0;
}

Put Text on a New Line

The Culprit: Text wraps wherever the browser decides, not necessarily where you want the visual break to happen.

The Fix: Insert a line break tag at the exact point you want the line to break. Unlike CSS-based wrapping, this forces a break at that specific spot regardless of container width.

<br>

Prevent Long Words From Overflowing

The Culprit: A long word or URL has no natural space for the browser to wrap at, so it just keeps going past the container edge.

The Fix: Allow the browser to break long words mid-word when necessary, rather than only at spaces.

.my-container {
  overflow-wrap: break-word;
}

Center Text

The Culprit: Text defaults to left-aligned unless told otherwise.

The Fix: Center inline text within its containing element. If a theme or page builder is overriding this, adding !important before the semicolon usually resolves it.

.my-section {
  text-align: center;
}

Left-Align Text

The Culprit: Some theme or block default is centering text that should read normally from the left edge.

The Fix: Explicitly set left alignment rather than relying on a default that something else may be overriding.

.my-section {
  text-align: left;
}

Add Space Below an Element

The Culprit: No margin is set between two stacked elements, so they sit flush against each other.

The Fix: Add space below the element, pushing whatever comes next further away.

.my-element {
  margin-bottom: 20px;
}

Add Space Inside an Element

The Culprit: No internal spacing is set, so content touches the container's own border or edge directly.

The Fix: Add internal space on every side of the element's content.

.my-box {
  padding: 20px;
}

Keep an Element From Getting Wider Than Its Container

The Culprit: The element has no width constraint, so it renders at its own natural size regardless of the space actually available.

The Fix: Cap the element's width at 100% of its container while letting height scale proportionally, so it never overflows.

.my-media {
  max-width: 100%;
  height: auto;
}

Make an Image Fill Its Container

The Culprit: A plain image tag displays at its natural aspect ratio, which may not match the shape of the space it needs to fill.

The Fix: Make the image fill its container fully, cropping automatically to maintain proportions.

.my-image {
  width: 100%;
  height: 100%;
  object-fit: cover;
}

Keep an Image Proportional

The Culprit: Both width and height are being forced to specific values that don't match the image's real aspect ratio.

The Fix: Let the image's width scale to its container while height adjusts automatically, preserving the original proportions.

.my-image {
  width: 100%;
  height: auto;
}

Round Image Corners

The Culprit: N/A – this is a deliberate style choice, not something to fix.

The Fix: Round the corners of the image.

.my-image {
  border-radius: 12px;
}

Create a Subtle Dark Image Overlay

The Culprit: A background image alone doesn't guarantee enough contrast for text placed on top of it.

The Fix: Add a translucent dark layer as part of the background treatment, darkening the image enough for light text to stay readable. Depends on how the rest of the section's background is structured.

.my-section {
  background-color: rgba(0, 0, 0, 0.4);
}

Control Background Image Positioning

The Culprit: A background image's default positioning may crop out the subject depending on the container's actual proportions.

The Fix: Center the background image within its container as a starting point.

.my-hero {
  background-position: center;
}

Hide Something on Mobile

The Culprit: An element that makes sense on desktop can be unnecessary or cluttered on a narrow mobile screen.

The Fix: Hide the element once the viewport narrows past a set breakpoint. Every page on this site uses 600px as the standard mobile breakpoint – matching that consistently avoids a component behaving differently from everything else.

@media (max-width: 600px) {
  .example { display: none; }
}

Show Something Only on Mobile

The Culprit: An element built specifically for mobile (like a condensed nav) shouldn't also show on desktop.

The Fix: Hide the mobile-only element once the viewport widens past the standard 600px breakpoint used across this site.

@media (min-width: 601px) {
  .mobile-only { display: none; }
}

Reduce Text Size on Mobile

The Culprit: A font size chosen for a wide desktop layout doesn't always scale down gracefully on its own.

The Fix: Reduce the font size specifically at mobile widths, using the site's standard 600px breakpoint.

@media (max-width: 600px) {
  .example { font-size: 18px; }
}

Reduce Spacing on Mobile

The Culprit: Generous desktop spacing can eat up a disproportionate amount of a small mobile viewport.

The Fix: Reduce internal spacing specifically at mobile widths, using the site's standard 600px breakpoint.

@media (max-width: 600px) {
  .example { padding: 20px; }
}

Prevent Horizontal Scrolling

The Culprit: An element somewhere on the page is rendering wider than the actual viewport.

The Fix: Hide horizontal overflow at the body level. Use this carefully as a general habit, since it can conceal a real underlying layout problem rather than fixing it – but on this site specifically, it is also the confirmed, deliberate fix for the known full-bleed 100vw scrollbar issue that several pages have hit (see the matching Error Guide entry): when a full-bleed element is the actual cause, this is the correct fix, not a workaround.

body {
  overflow-x: hidden;
}

Add Rounded Corners to a Card

The Culprit: N/A – this is a deliberate style choice, not something to fix.

The Fix: Round the corners of the card.

.my-card {
  border-radius: 16px;
}

Add a Subtle Border

The Culprit: N/A – this is a deliberate style choice, not something to fix.

The Fix: Add a subtle, semi-transparent border around the element.

.my-card {
  border: 1px solid rgba(255, 255, 255, 0.15);
}

Add a Simple Shadow

The Culprit: A flat card with no shadow can blend into a matching background color.

The Fix: Add a soft shadow around the element to lift it visually off the background.

.my-card {
  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.15);
}

Make a Button Stretch Across Its Container

The Culprit: A button defaults to only as wide as its own label and padding require.

The Fix: Make the button take up the full width of its container.

.my-button {
  width: 100%;
}

Change the Mouse Cursor

The Culprit: An element with a click handler (a div, a span) doesn't automatically get the pointer cursor the way a real link or button does.

The Fix: Change the cursor to the pointer style on hover, signaling the element is interactive.

.clickable-item {
  cursor: pointer;
}

Hide an Element Without Removing Its Space

The Culprit: display: none removes an element from the layout entirely, which can cause everything around it to shift.

The Fix: Hide the element visually while preserving its space in the layout – the key difference from display: none, which removes the element from the layout entirely rather than just hiding it in place.

.my-element {
  visibility: hidden;
}

Move an Element Slightly

The Culprit: A small positioning correction is needed, but changing margin or padding would shift other elements around it too.

The Fix: Shift the element visually without affecting the normal document flow around it. Depends on context – a repeated need for this on the same component is often a sign the underlying layout should be restructured instead, not a signal to keep nudging.

.my-element {
  transform: translateY(-5px);
}

WordPress Footer Template Requires Its Own Save Cycle

The Fix: 1. Identify whether the block is on a page or inside a template part (header, footer, sidebar).
2. If it is in a template part, navigate to Appearance → Editor and find the template.
3. Confirm the template shows unsaved changes and save it directly.
4. Clear caches after saving the template, not before.

iOS Safari Keyboard Scroll Collapses a Fixed-Position Popup Widget

The Fix: 1. Check whether `max-height` uses `100vh` — replace with `dvh`.
2. Check whether any `scroll` event listener closes or hides the widget.
3. Check whether the popup has `position: fixed` — if not, it may reposition unexpectedly when the viewport shifts.
Two fixes applied together:

**Fix 1 — Replace `vh` with `dvh`:**
```css
@media (max-width: 600px) {
  .widget-popup {
    max-height: 70dvh;
    position: fixed;
  }
}
```

**Fix 2 — Guard the scroll listener:**
```javascript
window.addEventListener('scroll', function() {
  if (popup.classList.contains('open')) return; // ignore scroll while widget is open
  // hide launcher logic...
});
```

Unicode Characters Inside Base64-Encoded JS Render as Garbled Text

The Fix: 1. Identify whether the garbled characters are special Unicode (em-dash, curly quotes, accented characters).
2. Check the original source file's encoding (`utf-8` vs. `latin-1`).
3. Look for any Unicode characters outside the basic ASCII range inside JS string literals.
Replace all non-ASCII characters in JS strings with plain ASCII equivalents before encoding:

- Em-dash `–` → hyphen `-`
- Left/right single quotes `'` `'` → straight apostrophe `'`
- Left/right double quotes `"` `"` → straight quote `"`

In Python before encoding:
```python
content = content.replace('u2013', '-')
content = content.replace('u2019', "'")

WordPress wptexturize Breaks JavaScript in Custom HTML Blocks

The Fix: 1. View the page source and find the “ block.
2. Look for curly quotes (`'` `'` or `"` `"`) where straight quotes should be.
3. Check whether the block is inside a WordPress template part or footer — these pass through the same wptexturize filter.
4. Check the browser console for a `SyntaxError` on script evaluation.
Base64-encode the entire JavaScript block and load it via `eval(atob("…"))`. Since the encoded string contains no quote characters, wptexturize has nothing to mangle.
The pattern:

```html
<script>eval(atob("BASE64_ENCODED_JS_HERE"))</script>
```

Encode in Python: `base64.b64encode(js.encode('utf-8')).decode('utf-8')`

Mobile breakpoint explicitly setting 1fr 1fr overrides any narrower fix

The Fix: 1. Find the lowest explicit grid column breakpoint in the CSS.
2. Confirm whether it is setting a specific column count (e.g., `1fr 1fr`) rather than just resetting other properties.
3. If so, that rule controls mobile layout regardless of what narrower breakpoints say — unless those narrower breakpoints also set the grid columns explicitly.
4. Verify any new breakpoints are inside the active “ tag, not in a comment block.
Edit the existing `600px` (or lowest active) breakpoint directly. Change `grid-template-columns: 1fr 1fr` to `grid-template-columns: 1fr`. Do not add a second narrower breakpoint — fix the one that's already firing.

```css
@media (max-width: 600px) {
  .grid-class { grid-template-columns: 1fr; }
}
```

When a View All Button Shows All Cards But “Show Fewer” Never Appears

The Fix: 1. Confirm `SHOW` value is less than the total card count — otherwise the button never appears
2. Check whether the ViewAll function hides the button (`display: none`) after click — this breaks the toggle
3. Verify the button text updates on both expand and collapse states

When a White Gap Appears at the Bottom of a Custom HTML Section

The Fix: 1. Open DevTools and click the element showing the wrong background — identify exactly which div is responsible
2. Count “ opens vs closes inside the suspected container
3. Check for comment markers (like “) that may give false confidence a div is closed
4. Verify the actual HTML structure rather than trusting the comment

When a WPCode Snippet Has No Location Set — and No Way to Set One

The Fix: 1. Open the snippet and look for an **Insertion** setting near the top of the editor (separate from Location).
2. Confirm whether it's set to Auto Insert, Shortcode, Page Builder, or another method — Location only exists under Auto Insert.
3. If it should be auto-inserted site-wide, switch Insertion to Auto Insert; the Location dropdown will then appear and can be set normally.
4. If it's intentionally a shortcode snippet, confirm the shortcode is actually placed somewhere — otherwise the snippet's code isn't running anywhere at all, even though it exists and is marked active.

When a Staging Fix “Looks Fine” But Isn’t Actually Live

The Fix: 1. Confirm you're actually viewing staging — check the address bar, not just the page content, especially after following in-page navigation links rather than typing the URL directly.
2. Clear the full cache stack in order, not just the browser cache, before concluding a fix didn't work.
3. Audit any Custom HTML blocks (nav menus, footers, embedded links) for hardcoded absolute domain URLs. Convert same-domain links to relative paths (`/page-slug/` instead of `https://domain.com/page-slug/`) so the same code behaves correctly on both staging and live.
4. To positively confirm you're looking at a fresh, correct version of a page — not a stale cache and not the wrong environment — make a small, visually obvious test change (e.g., an oversized font on one element), save, and hard-refresh. If the obvious change doesn't appear, the problem is caching or environment, not the original fix.

When an Accordion Opens But Never Closes, and No Error Appears Anywhere

The Fix: 1. Compare every class name referenced in the JavaScript against the actual class names used in the HTML markup, character by character. A single-letter typo in a class name inside a `querySelector` call will not produce any error.
2. Remember that `querySelector`/`querySelectorAll` matching zero elements is a silent no-op, not a failure state the browser will ever flag.
3. If part of a function's logic seems to be "missing" (like a reset or close step), check whether that step is actually running but simply matching nothing.

When a “Different Black” Section Turns Out to Be a Mislabeled Block, Not a Layout Bug

The Fix: 1. Use DevTools/List View to identify the exact block responsible, not just the visual area.
2. Check the block's HTML anchor name — a leftover or copy-pasted anchor from an earlier, unrelated block is a common source of confusion, especially in page builders where blocks get duplicated and repurposed over time.
3. Confirm the anchor name actually matches the block's current content before assuming a naming clue points to the real cause.
4. Compare the specific background color value (not just "looks dark") between the two sections — near-identical hex values are easy to mistake for a copy/paste of the same style, when they're actually two separate values that happened to land close to each other.

When One Domain Times Out on One Device While Everything Else Works Fine

The Fix: 1. Rule out the site/hosting first: if other domains work fine on the same network, and the affected domain works fine on a *different* network, the site itself is very unlikely to be the cause.
2. Flush DNS on the affected device as a first, low-effort step.
3. Test the domain on a completely different network (mobile hotspot) to isolate whether the problem is device-level or network-level.
4. If isolated to one network, suspect the router's own DNS cache rather than anything device-side.

When a Third-Party Search Widget’s Results Are Trapped in a Small Scrolling Box

The Fix: 1. Check whether the widget has a results *display mode* setting (Overlay vs. Full Width / inline / two-page results) in its own external configuration panel, separate from the embed code itself.
2. If available, switch away from an "overlay" or "floating" display mode to one that renders inline with the page's normal content flow.

WordPress FSE 404 Template Overridden by Full Site Editor Custom HTML Blocks

The Fix: Open Appearance → Editor → Templates → 404 → locate and delete the Custom HTML blocks containing the old content → add the new branded content as a fresh Custom HTML block → Save.

Preloaded Image 404 Persisting After Media Deletion

The Fix: Open Appearance → Editor → Templates → find the homepage template → locate the Cover block with the broken reference → remove the background image from within the block's settings directly.

When Fixing a Broken Script Accidentally Creates a Second, Conflicting Handler

The Fix: 1. Identify every place a given element's behavior might be bound, not just the one that's obviously broken.
2. Before patching a broken handler, check whether a working handler already exists elsewhere for the same element.
3. If two handlers do the same logical thing (like "toggle open, close others"), fixing the broken one without removing the redundant one will not restore correct behavior — it will create a race between two handlers that cancels the intended effect.

When a Styled Border Around a Third-Party Embed Is Missing Its Bottom Edge

The Fix: 1. Check whether a fixed `height` (rather than `min-height`) is being forced onto a container whose actual content comes from an external widget you don't fully control the internal padding of.
2. Check for `overflow: hidden` on the container or a parent element that could be clipping content taller than the fixed height.
3. Add `box-sizing: border-box` if border width isn't already being accounted for inside the stated dimensions.

When a Base64-Encoded Script Breaks Silently and Nothing on the Page Works

The Fix: The fix was to identify and remove the stray duplicated code fragment, re-balance the braces, then re-encode the corrected script back to base64 and swap it into the page.

When the Hero Height Needs to Change Without Changing the Video

The Fix: When a video hero is too tall on mobile:
1. Identify whether the video is a background video.
2. Inspect the surrounding Cover block.
3. Check the Cover's minimum height.
4. Check whether the video itself is actually determining the section height.
5. Adjust the container before modifying the media asset.
6. Verify that the overlaid content still fits comfortably.
7. Test the hero at several mobile viewport heights.

When the Mobile Version Needs a Different Layout Model

The Fix: When responsive CSS starts accumulating exceptions:
1. Count how many mobile-only offsets are being added.
2. Check whether transforms or negative margins are becoming necessary.
3. Ask whether the desktop structure still makes sense at the mobile width.
4. Consider Grid or Flexbox restructuring.
5. Group related content into predictable columns or rows.
6. Test intermediate widths, not just desktop and one phone size.
7. Remove obsolete positioning rules after changing the layout model.

Making a Hero Video Smaller Without Losing the Effect

The Fix: When optimizing a looping hero video:
1. Remove unnecessary duration.
2. Preserve only the motion needed to communicate the visual.
3. Make the beginning and ending visually compatible.
4. Compress the finished file.
5. Check the resulting file size.
6. Test the compressed version on the actual website.
7. Confirm that reducing the file size did not introduce an obvious loop artifact.

When a Short Hero Video Jumps at the Loop Point

The Culprit: The hero video was revised so the restart point produced a much smoother visual transition. The important troubleshooting principle was to examine the footage itself at the loop boundary rather than immediately assuming the HTML video element was malfunctioning.

Re-Uploading a File With the Same Name Doesn’t Replace It

The Fix: Don't upload a fresh copy to replace an existing file. Instead, open the existing Media Library item and use Replace Media (built into recent WordPress core versions, or available via a plugin like Enable Media Replace if your version doesn't show it). That swaps the actual file contents while keeping the same filename and URL — no code changes needed anywhere else on the site.
After replacing, clear caches in the usual order (build/optimization plugin cache → page cache plugin → any server or CDN-level cache) and hard-refresh, since a stale cache can still serve the old bytes even after the file itself has correctly been swapped.