Common Problems and Diagnostic Checklist
A useful diagnosis identifies the failing layer, exact time, visitor identity class, request channel, and first error without changing several settings at once.
Diagnosis starts with one reproducible symptom and follows the request through the smallest relevant layers: frontend visibility, REST transport, security, active assistant/model, knowledge routing, tools, OpenAI, channels, and logging. Recording the exact time, visitor state, page, and channel lets Chat History and server logs identify the same attempt.
Start with the smallest safe step: reproduce once with exact time, page, browser, login state, and channel. Do not consider the task finished before you make one reversible correction and rerun the same test; this is where the configuration is tested in the context that truly consumes it.
What this feature does and when to use it
Section titled “What this feature does and when to use it”Use this checklist for incidents and after updates.
Use this feature in the following situations:
- The launcher is missing, chat fails, an answer is wrong, or a request is blocked.
- A feature worked before an update or configuration change and now needs regression tracing.
- You need a sanitized evidence package for a developer or service provider.
Where to find it
Section titled “Where to find it”Before you begin
Section titled “Before you begin”- SmartSite Assistant is installed and activated.
- You are signed in with an account that can manage WordPress options.
Set it up step by step
Section titled “Set it up step by step”- Reproduce once with exact time, page, browser, login state, and channel.
- Check plugin version, activation, PHP 8.2+, and WordPress/PHP logs.
- Confirm visibility and page-cache behavior if the launcher is missing.
- Confirm active assistant, regular API key, and compatible model for chat failures.
- Confirm current knowledge states for wrong/missing source answers.
- Disable and isolate a failing tool; inspect destination logs.
- Separate WhatsApp connection, webhook verification, inbound event, security, OpenAI, and reply delivery.
- Inspect Chat History and Flagged Conversations with redaction.
- Make one reversible correction and rerun the same test.
Fields, controls, and important values
Section titled “Fields, controls, and important values”Each diagnostic points to a different layer of the conversation: browser delivery, WordPress handling, OpenAI access, knowledge retrieval, tools, security, or logs. Following the layers in order prevents unnecessary changes to instructions or models. The aim is to find where the expected information or action was lost, then fix only that part and retest a representative question.
| Field, control, or status | What SmartSite Assistant does with it | How to use it and why it matters |
|---|---|---|
| Chat History | Primary local evidence for status/error, model/tokens/duration, route, knowledge, tools, channel, and security. | Use “Chat History” to isolate the activity relevant to one question. The result can reveal where an answer failed, but the filter itself does not fix anything; improvement comes from the configuration change made after reviewing the evidence. |
| Knowledge sync modal | Per-item create/update/current/remove/error evidence. | Read “Knowledge sync modal” as evidence that a particular workflow stage did or did not finish. A completed badge cannot tell whether content is relevant, instructions are clear, or delivery works end to end, so pair it with a realistic test. |
| Test Connection / Tool Test / Security Tester | Layer-specific tests; tool tests may have side effects and security tests mutate transient counters. | Keep the tool associated with “Test Connection / Tool Test / Security Tester” disabled while checking valid, missing, malformed, and repeated inputs. Enable it only when the model description is narrow and the complete result cannot reveal or change anything beyond the approved purpose. |
| Server logs | Needed for PHP fatal, HTTP, timeout, REST, and remote request errors. | “Server logs” must match the receiver’s HTTPS address or request contract exactly. Test with synthetic data in a controlled destination and examine authentication plus the returned body; transport success alone does not prove the intended action finished. |
How to confirm it is working
Section titled “How to confirm it is working”Use a separate test session to confirm Common Problems and Diagnostic Checklist. This keeps existing login, browser storage, and response history from hiding the change, and it shows whether the result reaches the complete workflow rather than stopping at WordPress storage.
Practical example
Section titled “Practical example”A missing launcher for administrators but not anonymous users points first to visibility/cache variation, not OpenAI.
Recommended practice
Section titled “Recommended practice”- Change one part of Common Problems and Diagnostic Checklist at a time and keep a short record of the previous value and test result.
- Verify the saved result in the screen, visitor session, or connected service that actually consumes the setting.
Important warnings
Section titled “Important warnings”Common problems and focused checks
Section titled “Common problems and focused checks”| Problem | What to check and what to do next |
|---|---|
| Common Problems and Diagnostic Checklist is missing or does not match this guide. | Confirm the plugin is active and the account can manage WordPress options. Preserve logs and configuration evidence before changing files, caches, update state, or stored data. |
| A change on Common Problems and Diagnostic Checklist does not produce the expected result. | Keep the exact notice and test case, then review the browser console and WordPress/PHP log. Preserve logs and configuration evidence before changing files, caches, update state, or stored data. |
Screen reference
Section titled “Screen reference”- Capture
- Show a sanitized Chat History error detail with status, time, model, duration, routing, and error fields visible.
- Show
- Filters, error status, diagnostic sections, timestamps
- Viewport
- Desktop, 1440 × 900
- Annotate
- Use numbered callouts only for controls referenced in the procedure.
- Redact
- OpenAI keys, tokens, secrets, personal information, private URLs, IP addresses, and conversation text