# Troubleshooting

Common issues and how to resolve them.

---

## Workflow Editor Issues

### I don't see any nodes in the palette

- **Clear the cache**: `drush cr`
- **Check modules**: Verify that `flowdrop_node_processor` is enabled at **Administration > Extend** (`/admin/modules`).
- **Check node types**: Verify node types exist at **Administration > Structure > FlowDrop Node Type** (`/admin/structure/flowdrop-node-type`). If the list is empty, reinstall the `flowdrop_node_processor` module.

### I can't connect two ports

- **Check data type compatibility**: Port colors must match (or use "mixed" type ports). See [Connecting Nodes](workflows/connecting-nodes.md) for the full compatibility rules.
- **Check direction**: You must drag from an output port (right side) to an input port (left side). Input-to-input or output-to-output connections are not allowed.
- **Check port type**: Data ports connect to data ports, trigger ports connect to trigger ports. You cannot mix them.

### My changes aren't saving

- **Click Save**: Changes are not auto-saved. Click the **Save** button in the editor toolbar.
- **Check browser console**: Open browser developer tools (F12) and look for JavaScript errors that may indicate a problem.
- **Clear Drupal cache**: Run `drush cr` and reload the editor page.

---

## Execution Issues

### My workflow isn't running

- **Check workflow status**: The workflow must be enabled (status = true). Edit the workflow and verify its status.
- **Check pipelines**: View recent pipelines at **Administration > FlowDrop > Pipelines** (`/admin/flowdrop/pipelines`) to see if an execution was attempted.
- **Check logs**: Look for errors in Drupal's log:
  ```bash
  drush watchdog:show --type=flowdrop
  ```

### A node shows "failed" status

- **View the job details**: Click on the failed job in the pipeline detail page to see the error message.
- **Common causes**:
    - Missing required parameters (a required input port has no connection and no default value)
    - External service errors (for HttpRequest or AI nodes)
    - Entity not found (for EntityQuery or EntityContext nodes)
    - Permission issues

![Failed job detail](../screenshots/job-detail.png)

### Async workflows are stuck

If workflows executed with the asynchronous orchestrator appear stuck:

1. **Process the queues** manually:
   ```bash
   drush queue:run flowdrop_runtime_pipeline_execution
   drush queue:run flowdrop_runtime_job_execution
   ```

2. **Check that cron is running**: Async workflows depend on Drupal's queue system, which is processed during cron runs. Verify cron is configured and running.

3. **Check queue status**:
   ```bash
   drush queue:list
   ```

---

## Trigger Issues

### My trigger isn't firing

- **Check workflow is enabled**: The workflow referenced by the trigger must have status = true.
- **Check trigger config is enabled**: Review trigger configurations at **Administration > Structure > FlowDrop Trigger** (`/admin/structure/flowdrop-trigger`).
- **Verify conditions match**: For entity triggers, ensure the entity type and bundle conditions match the actual entity being created/updated.
- **Check trigger settings**: Review global trigger settings at `/admin/flowdrop/triggers/settings`.
- **Check logs**:
  ```bash
  drush watchdog:show --type=flowdrop_trigger
  ```

### Orphan trigger configurations

If you see log warnings like `Trigger @trigger references non-existent workflow @workflow`, this means a trigger configuration points to a deleted workflow. Delete the orphan trigger at **Administration > Structure > FlowDrop Trigger**.

---

## Monitoring

### Where to find execution results

![Pipeline listing page](../screenshots/pipeline-listing.png)

| What you need | Where to find it |
|---------------|-----------------|
| All pipeline runs | **Administration > FlowDrop > Pipelines** (`/admin/flowdrop/pipelines`) |
| Individual job details | Click on a pipeline, then click on a specific job |
| Drupal watchdog logs | **Reports > Recent log messages** (`/admin/reports/dblog`) |
| FlowDrop-specific logs | Filter by type `flowdrop` in watchdog |

### Checking logs via Drush

```bash
# All FlowDrop logs
drush watchdog:show --type=flowdrop

# Trigger-specific logs
drush watchdog:show --type=flowdrop_trigger

# Recent errors only
drush watchdog:show --severity=error
```

![Drupal log messages filtered for FlowDrop](../screenshots/drupal-logs-flowdrop.png)

---

## General

### Permission denied

Ensure the current user has the appropriate permissions:

| Permission | What it allows |
|------------|---------------|
| `administer flowdrop` | Full access to workflows, pipelines, and FlowDrop admin |
| `administer flowdrop triggers` | Create, edit, and delete trigger configurations |
| `view flowdrop triggers` | View trigger configuration list and details |

Permissions are managed at **Administration > People > Permissions** (`/admin/people/permissions`), filtering for "flowdrop".

### How to clear the cache

```bash
drush cr
```

Or navigate to **Administration > Configuration > Performance** and click **Clear all caches**.

### Where are the logs?

FlowDrop logs to Drupal's standard logging system (watchdog). View logs at:

- **UI**: **Reports > Recent log messages** (`/admin/reports/dblog`) — filter by type `flowdrop`
- **Drush**: `drush watchdog:show --type=flowdrop`
