Essentials
Troubleshooting
Common issues and solutions for Flowforge implementation.
Common Issues
Cards not draggable
Problem: Cards appear but cannot be dragged between columns.
Causes & Solutions:
- Missing
positionIdentifier: Add->positionIdentifier('position')to board config - Missing position column: Run migration with
$table->flowforgePositionColumn('position') - Null position values: Run
php artisan flowforge:repair-positions
// Correct configuration
public function board(Board $board): Board
{
return $board
->query(Task::query())
->columnIdentifier('status')
->positionIdentifier('position') // Required for drag-drop
->columns([...]);
}
Empty board showing
Problem: Board renders but no cards appear in any columns.
Debugging steps:
- Verify data exists:
// Add to board method temporarily
dd($this->getEloquentQuery()->get());
- Check status values match column identifiers:
// If your columns are 'todo', 'in_progress', 'done'
// Your data status field must contain exactly these values
- Ensure query returns records:
// Check for global scopes, soft deletes, etc.
->query(Task::withoutGlobalScopes()->get())
Actions not working
Problem: Card or column actions don't trigger or throw errors.
Solutions:
- Missing traits: Ensure component uses
InteractsWithActions,InteractsWithForms - Action configuration: Verify actions are properly configured with
->model()parameter - Permission issues: Check Filament policies and authorization
class TaskBoard extends BoardPage
{
use InteractsWithActions; // Required
use InteractsWithForms; // Required
public function board(Board $board): Board
{
return $board
->cardActions([
EditAction::make()->model(Task::class), // Model required
]);
}
}
New cards appear randomly
Problem: Cards created through column actions appear in random positions.
Solution: Add position generation in create action:
CreateAction::make()
->mutateFormDataUsing(function (array $data, array $arguments): array {
if (isset($arguments['column'])) {
$data['status'] = $arguments['column'];
$data['position'] = $this->getBoardPositionInColumn($arguments['column']);
}
return $data;
})
Drag-drop disabled with pagination
Problem: Cards show "Load All Cards" button and dragging is disabled.
Explanation: This is intentional behavior to prevent data corruption. Flowforge automatically disables drag-drop when pagination is active.
Solution: Users must click "Load All Cards" to enable safe reordering:
// Check if column is fully loaded
$this->isColumnFullyLoaded('todo'); // Returns false with pagination
// Load all cards programmatically
$this->loadAllItems('todo');
// Now drag-drop is enabled
$this->isColumnFullyLoaded('todo'); // Returns true
Styling issues
Problem: Board appears unstyled or has broken layout.
Solutions:
- Missing CSS: Ensure Flowforge views are included in your theme CSS
- Tailwind purging: Verify Tailwind isn't removing required classes
- Theme conflicts: Check for CSS conflicts with custom themes
/* Required in your theme CSS file */
@source "../../../../vendor/relaticle/flowforge/resources/views/**/*.blade.php";
Performance issues
Problem: Board loads slowly with many cards.
Solutions:
- Enable pagination: Remove
loadAllItems()calls to use default pagination - Optimize queries: Add database indexes on status and position columns
- Eager load relationships: Use
->with()in your query - Reduce card content: Minimize data displayed in card schema
// Optimized query example
->query(
Task::query()
->with(['assignee', 'priority']) // Eager load relationships
->select(['id', 'title', 'status', 'position']) // Select only needed fields
)
Debug Commands
Check position data integrity
php artisan flowforge:repair-positions
Verify database schema
php artisan migrate:status
Clear view cache
php artisan view:clear
Test Livewire functionality
// Add to board component temporarily
public function testDragDrop()
{
$task = Task::first();
$this->moveCard($task->id, 'in_progress');
dd($task->fresh()->status);
}
Getting Help
If you encounter issues not covered here:
- Check the GitHub issues: github.com/relaticle/flowforge/issues
- Review test examples: Look at the test suite for working examples
- Enable debug mode: Add
dd()statements to understand data flow - Create minimal reproduction: Isolate the issue in a fresh Laravel install