# Drupal Debugging

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-trebormc-drupal-ai-agents-drupal-debugging`
- **Verified:** Pending review
- **Seller:** [trebormc](https://agentstack.voostack.com/s/trebormc)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [trebormc](https://github.com/trebormc)
- **Source:** https://github.com/trebormc/drupal-ai-agents/tree/main/.claude/skills/drupal-debugging

## Install

```sh
agentstack add skill-trebormc-drupal-ai-agents-drupal-debugging
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## Environment

All commands via `ssh web`.
For Xdebug tracing/profiling (function call trees, execution timing), use the **xdebug-profiling** skill.

## Core Debugging & Information

| Command | Purpose |
|---------|---------|
| `ssh web drush status` | Drupal root, site path, DB connection |
| `ssh web drush core-status` | Detailed system status |
| `ssh web drush watchdog:show` | Recent log messages |
| `ssh web drush watchdog:show --severity=Error` | Only errors |
| `ssh web drush watchdog:show --count=50` | Last 50 entries |

## Cache Debugging

| Command | Purpose |
|---------|---------|
| `ssh web drush cache:clear render` | Clear only render cache |
| `ssh web drush cache:clear router` | Rebuild routing cache |
| `ssh web drush cache:clear css-js` | Clear CSS/JS aggregation cache |
| `ssh web drush cr` | Full cache rebuild (when in doubt, use this) |

## Configuration Debugging

| Command | Purpose |
|---------|---------|
| `ssh web drush config:get system.site` | Show config value |
| `ssh web drush config:set system.site name "New"` | Set config value |
| `ssh web drush config:status` | Show config sync status |

## PHP Evaluation (drush php:eval)

```bash
# Inspect state values
ssh web drush php:eval "var_dump(\Drupal::state()->get('system.cron_last'));"

# Check if function exists
ssh web drush php:eval "var_dump(function_exists('my_custom_function'));"

# List enabled modules
ssh web drush php:eval "print_r(array_keys(\Drupal::moduleHandler()->getModuleList()));"

# Pending entity definition updates
ssh web drush php:eval "print_r(\Drupal::entityDefinitionUpdateManager()->getChangeSummary());"

# List available services
ssh web drush php:eval "print_r(\Drupal::getContainer()->getServiceIds());"

# Check specific service exists
ssh web drush php:eval "var_dump(\Drupal::hasService('mymodule.my_service'));"

# Inspect entity field definitions
ssh web drush php:eval "print_r(array_keys(\Drupal::service('entity_field.manager')->getFieldDefinitions('node', 'article')));"
```

## Database Debugging

```bash
# Direct SQL query
ssh web drush sql:query "SELECT * FROM users_field_data LIMIT 5"

# Recent watchdog entries via SQL
ssh web drush sql:query "SELECT * FROM watchdog ORDER BY wid DESC LIMIT 20"

# List all entity types
ssh web drush php:eval "print_r(array_keys(\Drupal::entityTypeManager()->getDefinitions()));"

# Check route definitions (grep runs in YOUR container — this works)
ssh web drush route | grep mymodule
```

## Container & Log Debugging

```bash
# Web container error logs (last 50 lines)
ssh web tail -n 50 /var/log/apache2/error.log

# Database container logs (last 50 lines)
ssh web tail -n 50 /var/log/mysql/error.log

# Test database connection
ssh web drush sql:connect
```

## Common Troubleshooting Patterns

| Problem | Debug command |
|---------|-------------|
| Class not found | `ssh web composer dump-autoload && ssh web drush cr` |
| Service not found | Check services.yml syntax, then `ssh web drush cr` |
| Plugin not discovered | `ssh web drush php:eval "print_r(array_keys(\Drupal::service('plugin.manager.block')->getDefinitions()));"` |
| Route not working | Run `ssh web drush route` and search the output for your route; if missing, `ssh web drush cr` |
| Entity field missing | `ssh web drush php:eval "print_r(\Drupal::entityDefinitionUpdateManager()->getChangeSummary());"` |

## Twig Debugging

```bash
# Enable Twig debugging via Drush (Drush 12.5+; use manual setup below for older Drush)
ssh web drush twig:debug on

# Check theme registry
ssh web drush php:eval "print_r(array_keys(\Drupal::service('theme.registry')->get()));"
```

Manual setup for persistent Twig debugging:

**In `settings.local.php`:**
```php
$settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';
```

**In `sites/development.services.yml`:**
```yaml
parameters:
  twig.config:
    debug: true
    auto_reload: true
    cache: false
```

With Twig debugging enabled, HTML comments show template suggestions and the active template path.

## Theme Troubleshooting

| Problem | Fix |
|---------|-----|
| Template not being used | Check filename matches Drupal suggestion exactly. Enable Twig debug, check HTML comments, `drush cr` |
| Tailwind classes not working | Recompile: `ssh web npm run build --prefix $DDEV_DOCROOT/themes/custom/THEME`, `ssh web drush cr`, hard refresh (Ctrl+Shift+R) |
| JavaScript not executing | Verify library attached (`{{ attach_library() }}`), check console for errors, verify `mytheme.libraries.yml` syntax, `drush cr` |
| Cache issues | Disable render/page/dynamic_page caches in `settings.local.php` using `cache.backend.null` |
| Template suggestions not appearing | `ssh web drush twig:debug`, `drush cr` |
| Preprocess variables unavailable | Check hook name (`mytheme_preprocess_node`), verify theme is active, `drush cr`. Debug with `kint($variables)` |
| CSS/JS libraries not loading | `ssh web drush php:eval "print_r(array_keys(\Drupal::service('library.discovery')->getLibrariesByExtension('mytheme')));"` |
| Field not rendering correctly | `ssh web drush php:eval "print_r(\Drupal::service('entity_field.manager')->getFieldDefinitions('node', 'article')['field_name']->getSettings());"` |
| Images not displaying | `ssh web drush image:flush --all` and check file permissions |
| Translations not appearing | `ssh web drush locale:clear-status && ssh web drush locale:update` |

## Test Troubleshooting

| Problem | Fix |
|---------|-----|
| "Class not found" in tests | `ssh web composer dump-autoload`. Verify namespace matches directory path |
| Kernel: "Entity type not found" | Add module to `$modules`, call `$this->installEntitySchema('entity_type')` in `setUp()` |
| Functional: "Route not found" | Verify module in `$modules`, try `$this->rebuildContainer()`, check the route exists with `ssh web drush route` |
| "SQLSTATE no such table" | Call `$this->installEntitySchema('user')`, `$this->installSchema('node', ['node_access'])` in `setUp()` |
| "Service not found" | Ensure module with service is in `$modules`. Get via `$this->container->get('service.id')` |
| Tests pass locally, fail in CI | Check hardcoded paths/URLs, timezone settings, race conditions, use transactions |
| "Test was not supposed to have output" | Don't use print/echo. Capture with `$this->expectOutputString('expected')` |
| "Maximum function nesting level" | `ssh web php -d xdebug.max_nesting_level=500 ./vendor/bin/phpunit ...` |
| Functional: "Failed to connect localhost:80" | Ensure `SIMPLETEST_BASE_URL` set in phpunit.xml or use `$this->setBaseUrl('http://web')` |
| "Could not connect to database" | `ssh web drush sql:query "CREATE DATABASE IF NOT EXISTS test;"`. SIMPLETEST_DB: `mysql://db:db@db/test` |
| Browser screenshots not saving | `ssh web mkdir -p /var/www/html/sites/simpletest/browser_output && ssh web chmod 777 /var/www/html/sites/simpletest/browser_output` |
| "Theme not found" in functional | Set `protected $defaultTheme = 'stark';` or install custom theme in `setUp()` |
| Test timeout issues | `--timeout=300` flag. Check for unnecessary modules in `$modules` |
| "Test site directory exists already" | `ssh web rm -rf /var/www/html/sites/simpletest/` then recreate browser_output dir |

## Performance Troubleshooting

| Problem | Fix |
|---------|-----|
| Page not caching | Check for `max-age: 0` in any render array. Look for session-dependent code. Enable `http.response.debug_cacheability_headers: true` in development.services.yml |
| Cache not invalidating | Verify cache tags are correct. Test: `ssh web drush php:eval "\Drupal::service('cache_tags.invalidator')->invalidateTags(['node:123']);"` |
| Queries still slow | Check indexes: `ssh web drush sqlq "EXPLAIN SELECT ..."`. Add custom index in `hook_schema()` |
| Memory issues | `ssh web drush php:eval "echo 'Peak: ' . round(memory_get_peak_usage(true) / 1024 / 1024) . 'MB';"`. Use `resetCache()` in batch operations |
| Views performance | Enable query caching + rendered output caching. Configure pager (no unlimited). Use Search API for complex queries |

## Verification

```bash
# Quick health check
ssh web drush status --field=drupal-version
ssh web drush core:requirements --severity=2
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [trebormc](https://github.com/trebormc)
- **Source:** [trebormc/drupal-ai-agents](https://github.com/trebormc/drupal-ai-agents)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-trebormc-drupal-ai-agents-drupal-debugging
- Seller: https://agentstack.voostack.com/s/trebormc
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.