Troubleshooting Template Generator

Generate helpful troubleshooting guides and FAQ documentation.

Document Structure

markdown

# Troubleshooting

## Quick Fixes
{common issues with quick solutions}

## Installation Issues
{installation problems}

## Configuration Issues
{config problems}

## Runtime Errors
{errors during execution}

## FAQ
{frequently asked questions}

## Getting Help
{how to report issues}

Section Templates

Quick Fixes Section

markdown

## Quick Fixes

### Reset to Known Good State

```bash
# Clear cache
rm -rf var/cache/*

# Reinstall dependencies
rm -rf vendor/ composer.lock
composer install

# Verify installation
php vendor/bin/package verify

Check Common Issues

Symptom	Quick Fix
"Class not found"	Run `composer dump-autoload`
Permission denied	Run `chmod -R 755 var/`
Config not loading	Check `.env` file exists
Connection refused	Verify service is running

code


### Installation Issues Section

```markdown
## Installation Issues

### Composer Install Fails

**Symptom:**

Your requirements could not be resolved to an installable set of packages.

code


**Solutions:**

1. **Update Composer:**
   ```bash
   composer self-update

•
Clear Composer cache:
bash
```
composer clear-cache
```
•
Check PHP version:
bash
```
php -v
# Must be 8.5 or higher
```
•
Check required extensions:
bash
```
php -m | grep -E "json|pdo|mbstring"
```

Extension Not Found

Symptom:

code

PHP Fatal error: Uncaught Error: Call to undefined function json_encode()

Solution:

Install missing PHP extension:

bash

# Ubuntu/Debian
sudo apt-get install php8.5-json

# macOS with Homebrew
brew install php@8.5

# Verify
php -m | grep json

code


### Configuration Issues Section

```markdown
## Configuration Issues

### Environment Variables Not Loading

**Symptom:**

API key not configured

code


**Checklist:**

1. **Verify `.env` file exists:**
   ```bash
   ls -la .env

•
Check variable is set:
bash
```
grep "PACKAGE_API_KEY" .env
```

•

Verify no syntax errors:

bash

# Values with spaces need quotes
PACKAGE_NAME="My App Name"  # ✅ Correct
PACKAGE_NAME=My App Name    # ❌ Wrong

•

Clear config cache:

bash

php artisan config:clear  # Laravel
rm var/cache/config.php   # Other frameworks

Invalid Configuration Value

Symptom:

code

Configuration error: 'timeout' must be a positive integer

Solution:

Check config/package.php:

php

// ❌ Wrong
'timeout' => '30',  // String instead of int

// ✅ Correct
'timeout' => 30,    // Integer

code


### Runtime Errors Section

```markdown
## Runtime Errors

### Connection Timeout

**Symptom:**

Error: Connection timed out after 30 seconds

code


**Possible Causes:**

1. **Network issues** — Check connectivity
2. **Firewall blocking** — Check outbound rules
3. **Service down** — Check status page
4. **Timeout too short** — Increase timeout

**Solutions:**

```php
// Increase timeout
$client = new Client([
    'timeout' => 60,  // 60 seconds
]);

bash

# Test connectivity
curl -v https://api.example.com/health

Rate Limit Exceeded

Symptom:

json

{
    "error": {
        "code": "RATE_LIMITED",
        "message": "Too many requests"
    }
}

Solutions:

•

Implement backoff:

php

$client = new Client([
    'retry' => [
        'max_attempts' => 3,
        'delay' => 1000,  // ms
    ],
]);

•

Cache responses:

php

$cache = new RedisCache();
$client = new Client(['cache' => $cache]);

•
Upgrade plan for higher limits

Memory Limit Exceeded

Symptom:

code

PHP Fatal error: Allowed memory size of 134217728 bytes exhausted

Solutions:

•

Process in batches:

php

foreach ($client->paginate(100) as $batch) {
    process($batch);
}

•
Increase memory limit:
php
```
ini_set('memory_limit', '256M');
```

•

Use generators:

php

foreach ($client->stream() as $item) {
    yield process($item);
}

code


### FAQ Section

```markdown
## FAQ

### General

<details>
<summary><strong>Q: What PHP version is required?</strong></summary>

PHP 8.5 or higher is required. Check your version:

```bash
php -v

</details> <details> <summary>Q: Is this library production-ready?</summary>

Yes, the library is used in production by many projects. We follow semantic versioning and maintain backward compatibility within major versions.

</details>

Configuration

<details> <summary>Q: How do I configure multiple environments?</summary>

Use environment-specific .env files:

bash

.env           # Base configuration
.env.local     # Local overrides (not committed)
.env.test      # Test environment
.env.prod      # Production environment

</details> <details> <summary>Q: Can I use environment variables directly?</summary>

Yes, you can pass configuration directly:

php

$client = new Client([
    'api_key' => getenv('MY_API_KEY'),
]);

</details>

Performance

<details> <summary>Q: How can I improve performance?</summary>

•Enable caching — Reduces API calls
•Use connection pooling — Reuse connections
•Batch requests — Reduce round trips
•Use async — Parallel processing

php

$client = new Client([
    'cache' => new RedisCache(),
    'pool_size' => 10,
]);

</details> ```

Getting Help Section

markdown

## Getting Help

### Before Asking for Help

1. **Search existing issues:** [GitHub Issues](https://github.com/vendor/package/issues)
2. **Check documentation:** [Docs](https://docs.example.com)
3. **Review changelog:** [CHANGELOG.md](CHANGELOG.md)

### Collect Debug Information

Run this command and include output in your issue:

```bash
php -v
composer show vendor/package
php -m | grep -E "json|pdo|curl"

Report a Bug

Create an issue with:

•Description — What happened?
•Expected — What should have happened?
•Steps to reproduce — How can we reproduce it?
•Environment — PHP version, OS, package version
•Error message — Full stack trace

Ask a Question

•💬 GitHub Discussions
•📚 Stack Overflow

code


## Complete Example

```markdown
# Troubleshooting

## Quick Fixes

| Problem | Solution |
|---------|----------|
| Class not found | `composer dump-autoload` |
| Permission denied | `chmod -R 755 var/` |
| Config missing | Check `.env` exists |

## Common Errors

### "Invalid API Key"

**Symptom:**

Error: Invalid API key provided

code


**Solutions:**

1. Verify key in `.env`:
   ```bash
   grep "API_KEY" .env

•

Check for extra whitespace:

code

API_KEY=abc123   # ✅ No quotes needed
API_KEY= abc123  # ❌ Extra space

•
Regenerate key at dashboard

FAQ

<details> <summary>Q: Why am I getting rate limited?</summary>

Free tier allows 100 requests/hour. Upgrade for more.

</details>

Get Help

•📖 Documentation
•🐛 Report Bug
•💬 Ask Question

code


## Generation Instructions

When generating troubleshooting docs:

1. **Start with symptoms** — What user sees
2. **Explain causes** — Why it happens
3. **Provide solutions** — Step-by-step fixes
4. **Include verification** — How to confirm fix
5. **Use collapsible FAQ** — Reduce scrolling
6. **Link to help** — Where to get more support