10 Troubleshooting

Troubleshooting

Common issues and solutions when using Ghost Writer.

---

Content Still Flagged as AI

Symptom: GPTZero, Pangram, or Originality.ai still returns high AI probability after generation.

Solutions

1. Check phrase blacklist

   • Run the Check action on your content
   • Look for phraseBlacklistHits in the style/QA output
   • Manually replace any remaining blacklisted phrases with alternatives from the phrase blacklist replacements

2. Increase burstiness

   • Use a voice profile with higher burstiness (e.g., john-williams or casual)
   • Ensure sentence length stdev is ≥5; if not, the QA revision loop should address it
   • Add more fragments and varied sentence lengths in your topic/context

3. Try a different voice profile

   • technical and agency have lower burstiness
   • Switch to john-williams or casual for more variation
   • Or create a custom profile from high-burstiness writing samples

4. Add context

   • Provide specific context (audience, data points, examples)
   • Domain-specific vocabulary reduces AI signal (Check 27)

5. Regenerate with variants

   • Set variants: 2 or 3 to get multiple outputs
   • Each variant uses a different temperature (0.85, 0.89, 0.93)
   • Pick the one with the best detection scores

---

Detection API Errors

Symptom: gptzero.error, pangram.error, or originality.error in the response.

Solutions

1. Check API keys

   • Ensure GPTZERO_API_KEY, PANGRAM_API_KEY, ORIGINALITY_API_KEY are set in environment
   • Keys are typically in config/local.yaml or Cloudflare Workers secrets

2. Rate limits

   • Each provider has its own limits
   • If you hit limits, reduce request frequency or upgrade your plan
   • Ghost Writer calls all three in parallel; one failure doesn't block the others

3. Request size

   • Some APIs limit input length (e.g., 50K chars)
   • If content is very long, consider checking in chunks or truncating

4. Network/timeouts

   • Detection calls run in parallel; slow networks can cause timeouts
   • Increase timeout if self-hosting; check provider status pages

---

Content Too Long or Too Short

Symptom: Output doesn't match expected length for the platform.

Solutions

1. Adjust length parameter

   • length is in words (default 500)
   • For LinkedIn: try 100–300 words
   • For blog: try 800–2000
   • For email: try 50–150

2. Check platform spec

   • Each type has bestLength and maxChars
   • See Content Type Playbooks
   • Adapter truncates at maxChars; specify length to avoid over-generation

3. Be explicit in topic/context

   • "Write a 150-word LinkedIn post about X" helps
   • "Brief email, 3 paragraphs max" in context

---

Voice Doesn't Match

Symptom: Output doesn't sound like the selected voice profile.

Solutions

1. Import more samples

   • Custom profiles need at least 2 samples; 3+ recommended
   • Each sample should be 50+ chars; 500+ preferred
   • Use diverse content (LinkedIn, email, blog) from the same author

2. Check domain terms

   • Voice profiles include domainTerms
   • If your niche isn't covered, create a custom profile with samples that use your terminology

3. Verify profile is loaded

   • Built-in profiles: john-williams, agency, technical, casual
   • Custom profiles require CONTEXT KV for storage
   • Use action: "get" to confirm profile exists

---

QA Check Failures

Symptom: qa.passed: false, hardFails or softFails > 0.

Which checks to prioritize

• Hard fails — Must fix. Content is revised automatically up to 3 times
• Soft fails — Up to 3 allowed; >3 triggers revision

Common hard fails

Check	Fix
#1 Sentence Length Variance	Add short and long sentences; increase temperature
#5 Short Sentence Presence	Add at least one sentence ≤5 words
#8 Conjunction Starters	Start a paragraph with And/But/So
#13 Phrase Blacklist	Replace blacklisted phrases; revision does this automatically
#19 Unicode Normalization	normalizeText() should strip these; check input source
#34 Platform Format Compliance	Content over max chars; reduce length or truncate

How the revision loop works

1. Blacklist hits → replaced with random alternatives
2. Remaining fails → revision prompt sent to GPT with failed check details
3. Revised content re-checked
4. Up to 3 revision cycles

If still failing after 3 cycles, output is returned with passed: false; you can manually edit or regenerate.

---

Rate Limits

Symptom: 429 or rate limit errors from APIs.

Middleware limits (if applicable)

Endpoint	Limit
POST /api/writing-agent (generate)	10 req/min
POST /api/writing-agent (check)	15 req/min
POST /api/writing-agent-voice	10 req/min

These are typical middleware limits; actual values depend on your deployment.

Provider limits

• OpenAI: Varies by tier; check your dashboard
• GPTZero: Check your plan
• Pangram: Check your plan
• Originality.ai: Check your plan

Mitigation

• Use variants: 1 to reduce generation calls
• Disable detectors for draft runs: detectorsEnabled: false
• Cache voice profile analysis; don't re-analyze the same samples repeatedly