Troubleshooting

Common issues and solutions for WireChat

Common Issues

This guide covers common problems you might encounter when using WireChat and how to solve them.

Installation & Setup Issues

Namespace not found after installation

Problem: Class Wirechat\Wirechat\... not found

Solution:

1. Clear autoload cache

   composer dump-autoload
   
2. Verify package is installed

   composer show wirechat/wirechat
   
3. Check namespace in files

   Ensure you’re using the correct namespace:

   use Wirechat\Wirechat\Traits\InteractsWithWireChat;
   

   Not the old namespace:

   use Namu\WireChat\Traits\Chatable; // ❌ Old
   

Migration errors during installation

Problem: Database migration fails with column type errors

Solution:

For new installations, ensure your config/wirechat.php is published:

php artisan vendor:publish --tag=wirechat-config

If using UUIDs, set this before running migrations:

'uses_uuid_for_conversations' => true,

This setting only affects new installations. Do not change it on existing applications.

Table prefix not applying

Problem: Tables are created without the configured prefix

Solution:

The table_prefix setting in config/wirechat.php only affects new installations. If you’ve already run migrations, you’ll need to:

1. Drop existing WireChat tables
2. Update the config
3. Re-run migrations

php artisan migrate:rollback --path=vendor/wirechat/wirechat/database/migrations
php artisan migrate --path=vendor/wirechat/wirechat/database/migrations

User Model Issues

User search not working

Problem: Cannot find users when creating conversations

Solution:

Ensure your User model implements the WireChatUser interface:

use Wirechat\Wirechat\Contracts\WireChatUser;
use Wirechat\Wirechat\Traits\InteractsWithWireChat;

class User extends Authenticatable implements WireChatUser
{
    use InteractsWithWireChat;
}

The interface requires these accessor methods:

• getWirechatAvatarUrlAttribute()
• getWirechatProfileUrlAttribute()
• getWirechatDisplayNameAttribute()

Avatar images not displaying

Problem: User avatars show as broken images or SVG fallback

Solution:

Implement the getWirechatAvatarUrlAttribute() method in your User model:

public function getWirechatAvatarUrlAttribute(): ?string
{
    return $this->avatar 
        ? Storage::url($this->avatar)
        : null;
}

WireChat will automatically fall back to an SVG avatar if the method returns null or the image fails to load.

Participant limit errors

Problem: “Private conversations cannot have more than two participants”

Solution:

This is expected behavior. Private conversations are limited to 2 participants and self conversations to 1 participant. The limits are enforced in Conversation.php:219-233.

If you need more participants, create a GROUP conversation instead:

use Wirechat\Wirechat\Enums\ConversationType;

$conversation = Conversation::create([
    'type' => ConversationType::GROUP,
]);

Message & Attachment Issues

Attachments not uploading

Problem: File uploads fail or files are not saved

Solution:

1. Check storage configuration

   Verify your config/wirechat.php storage settings:

   'storage' => [
       'disk' => 'public', // or 's3', etc.
       'visibility' => 'public',
       'directories' => [
           'attachments' => 'attachments',
       ],
   ],
   
2. Ensure disk is configured

   Check config/filesystems.php has the disk defined:

   'public' => [
       'driver' => 'local',
       'root' => storage_path('app/public'),
       'url' => env('APP_URL').'/storage',
       'visibility' => 'public',
   ],
   
3. Create storage symlink

   php artisan storage:link
   
4. Check file permissions

   Ensure Laravel can write to the storage directory:

   chmod -R 775 storage
   chown -R www-data:www-data storage
   

S3 attachment uploads fail

Problem: Attachments don’t work with S3 storage

Solution:

WireChat v0.2.5+ uses single file uploads to support S3. Ensure:

1. Your S3 disk is properly configured in config/filesystems.php
2. Update WireChat config to use S3:
   'storage' => [
       'disk' => 's3',
       'visibility' => 'private', // S3 supports private files
   ],
   
3. For private files, WireChat will automatically generate temporary URLs

Messages not appearing in real-time

Problem: Messages only appear after page refresh

Solution:

1. Check broadcasting is configured

   Ensure you have a broadcasting driver set in .env:

   BROADCAST_DRIVER=pusher # or reverb, redis, etc.
   
2. Verify Echo is installed

   npm install --save-dev laravel-echo pusher-js
   
3. Check channel name format

   For v0.3.x, ensure you’re using the encoded type format:

   Echo.private(`participant.${encodedType}.${userId}`)
   

Messages deleted by one user affect others

Problem: Deleting messages removes them for all participants

Solution:

This is expected in v0.0.x - v0.1.x. WireChat v0.3.0+ implements Smart Deletes where messages are only hidden for the user who deleted them, not removed from the database.

The deletion is tracked via the actions table with type Actions::DELETE scoped to each participant.

Migration Issues (v0.2.x → v0.3.x)

Namespace upgrade command fails on Windows

Problem: wirechat:upgrade-namespace-to-v0.3x fails with “find/sed not found”

Solution:

The command requires Unix tools. Options:

1. Use Git Bash (included with Git for Windows)
2. Use WSL (Windows Subsystem for Linux)
3. Manual replacement in your IDE:
   • Find: Namu\\WireChat or Namu\\Wirechat
   • Replace: Wirechat\\Wirechat

Polymorphic column upgrade fails

Problem: wirechat:upgrade-morph-columns fails with constraint errors

Solution:

1. Check for foreign key constraints

   If you’ve added custom foreign keys on polymorphic columns, you may need to drop them first.

2. For SQLite users

   SQLite doesn’t support in-place column alterations. You’ll need to:

   1. Backup your data
   2. Run php artisan migrate:fresh (⚠️ destroys data)
   3. Or manually rebuild the tables
3. Use dry-run first

   php artisan wirechat:upgrade-morph-columns --dry-run
   

   This shows what would change without applying it.

Old trait name still in use after migration

Problem: Code still uses Chatable trait after namespace upgrade

Solution:

The namespace upgrade command only changes the namespace, not trait names. Manually update:

// Old
use Wirechat\Wirechat\Traits\Chatable;

// New
use Wirechat\Wirechat\Traits\InteractsWithWireChat;

Chatable is still available but deprecated. It will be removed in v1.0.

Permission & Authorization Issues

Cannot add participant - already in conversation

Problem: Error 422: “Participant is already in the conversation”

Solution:

This error is thrown when trying to add a user who is already a participant. Check if the user exists first:

$participant = $conversation->participant($user);

if (!$participant) {
    $conversation->addParticipant($user);
}

Cannot add participant removed by admin

Problem: Error 403: “Cannot add [user] because they were removed from the group by an Admin”

Solution:

When a user is removed by an admin, they can only be re-added by explicitly undoing the removal:

$conversation->addParticipant(
    user: $user,
    role: ParticipantRole::PARTICIPANT,
    undoAdminRemovalAction: true
);

This is implemented in Conversation.php:179-216.

User cannot rejoin after leaving group

Problem: Error 403: “Cannot add [user] because they left the group”

Solution:

When a user voluntarily exits a group, they cannot be re-added automatically. This is by design to respect the user’s choice to leave.

Only admin removal can be undone (see above).

Performance Issues

Slow conversation loading

Problem: Conversations take a long time to load

Solution:

1. Ensure indexes exist

   After running wirechat:upgrade-morph-columns, verify indexes were created:

   • actions_actionable_idx
   • actions_actor_idx
   • actions_type_idx
   • attachments_attachable_idx
2. Eager load relationships

   $conversations = Conversation::with([
       'participants.participantable',
       'lastMessage',
       'group'
   ])->get();
   
3. Use pagination

   For large conversation lists, paginate:

   $conversations = Conversation::paginate(20);
   

High database query count

Problem: Too many queries executed per page load

Solution:

Enable query logging to identify N+1 problems:

\DB::enableQueryLog();
// Your code
dd(\DB::getQueryLog());

Common fixes:

• Eager load participants.participantable
• Eager load lastMessage
• Cache conversation lists

View & UI Issues

Styles not applying correctly

Problem: WireChat components look unstyled

Solution:

1. Clear view cache

   php artisan view:clear
   
2. Ensure Tailwind is configured

   Add WireChat paths to tailwind.config.js:

   content: [
       './resources/**/*.blade.php',
       './vendor/wirechat/wirechat/resources/views/**/*.blade.php',
   ],
   
3. Rebuild assets

   npm run build
   

Dark mode not working

Problem: Dark mode theme variables not applying

Solution:

Ensure your theme configuration includes dark mode variables:

'theme' => [
    '--wirechat-primary' => '#3b82f6',
    '--wirechat-dark-bg' => '#1f2937',
    // ... other variables
],

See the Theming Guide for full configuration.

Getting Help

If your issue isn’t covered here, please:

1. Check the GitHub Issues
2. Search existing discussions
3. Open a new issue with:
   • WireChat version
   • Laravel version
   • Steps to reproduce
   • Error messages

WireChat is currently in beta (v0.3.0-beta4). Some features may have bugs or change before the stable release.