DEV Community: Manish Chaudhary

Understanding Laravel's Mutex and WithoutOverlapping: Preventing Concurrent Command Execution

Manish Chaudhary — Thu, 29 Jan 2026 08:59:57 +0000

Introduction

Have you ever run a Laravel Artisan command and seen the mysterious message "Has Mutex"? This article explains what mutex locks are, why Laravel uses them, and how to work with the withoutOverlapping() feature to prevent concurrent command execution.

What is a Mutex?

A mutex (mutual exclusion) is a synchronization mechanism that prevents multiple processes from accessing the same resource simultaneously. Think of it like a bathroom lock - only one person can use it at a time, and others must wait until it's free.

In Laravel, mutexes are used to ensure that scheduled commands don't run multiple instances at the same time, which could lead to:

Duplicate data processing
Race conditions
Database inconsistencies
Resource exhaustion

The `withoutOverlapping()` Method

Laravel's task scheduler provides the withoutOverlapping() method to prevent a scheduled task from running if a previous instance is still executing.

Basic Usage

// app/Console/Kernel.php

protected function schedule(Schedule $schedule): void
{
    $schedule->command('orders:process')
        ->everyTenMinutes()
        ->withoutOverlapping();
}

How It Works

Before execution: Laravel attempts to acquire a mutex lock
If lock acquired: The command runs normally
If lock exists: The command is skipped (displays "Has Mutex")
After execution: The lock is automatically released

Lock Expiration

By default, locks expire after 24 hours. You can customize this:

$schedule->command('orders:process')
    ->everyTenMinutes()
    ->withoutOverlapping(expiresAt: 60); // Lock expires after 60 minutes

Common Scenarios and Solutions

Scenario 1: "Has Mutex" When Running Manually

Problem: You try to run a command manually but see "Has Mutex"

Causes:

The scheduled job is currently running
A previous run crashed and didn't release the lock

Solution:

php artisan schedule:clear-cache

Scenario 2: Command Crashes Mid-Execution

Problem: If a command crashes or times out, the mutex lock may not be released.

Solution: Clear the schedule cache or wait for the lock to expire.

Scenario 3: Running Commands in Multiple Environments

Problem: Different environments (local, staging) might share the same cache driver.

Solution: Use different cache prefixes per environment in config/cache.php:

'prefix' => env('CACHE_PREFIX', 'laravel_' . env('APP_ENV')),

The Isolatable Interface

For commands that should never run concurrently regardless of how they're invoked (scheduler, manual, or queued), implement the Isolatable interface:

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Contracts\Console\Isolatable;

class ProcessOrders extends Command implements Isolatable
{
    protected $signature = 'orders:process';

    protected $description = 'Process pending orders';

    public function handle(): void
    {
        // This will never run concurrently
    }
}

Running with Isolation Flag

You can also use the --isolated flag when running any command:

php artisan orders:process --isolated

If another instance is running, the command exits with code 0 (success) by default. To change the exit code:

php artisan orders:process --isolated=12

Where Are Mutex Locks Stored?

Mutex locks are stored in your configured cache driver. Common locations:

Cache Driver	Lock Location
`file`	`storage/framework/cache/`
`redis`	Redis database
`database`	`cache` table
`memcached`	Memcached server

Manually Clearing File-Based Locks

# Clear all cache (including mutex locks)
php artisan cache:clear

# Or specifically clear schedule cache
php artisan schedule:clear-cache

Best Practices

1. Set Appropriate Lock Expiration

// For quick commands (< 5 minutes)
->withoutOverlapping(expiresAt: 10)

// For long-running commands (30+ minutes)
->withoutOverlapping(expiresAt: 120)

2. Use `runInBackground()` for Long Commands

$schedule->command('reports:generate')
    ->daily()
    ->withoutOverlapping()
    ->runInBackground(); // Prevents blocking the scheduler

3. Add Logging for Debugging

public function handle(): void
{
    Log::info('Command started: ' . now());

    // ... your logic

    Log::info('Command completed: ' . now());
}

4. Handle Graceful Shutdown

public function handle(): void
{
    foreach ($items as $item) {
        if ($this->shouldStop()) {
            Log::info('Command stopped gracefully');
            return;
        }

        $this->processItem($item);
    }
}

private function shouldStop(): bool
{
    return app()->isDownForMaintenance();
}

Real-World Example

Here's how we use withoutOverlapping() for our Avalara tax adjustment command:

// app/Console/Kernel.php

$schedule->command('orders:adjust-for-avatax')
    ->everyTenMinutes()
    ->withoutOverlapping()
    ->runInBackground();

This ensures:

Only one instance processes orders at a time
No duplicate tax adjustments are sent to Avalara
The scheduler isn't blocked while the command runs

Troubleshooting Checklist

Issue	Solution
"Has Mutex" message	Run `php artisan schedule:clear-cache`
Lock never releases	Check if command is timing out; increase `expiresAt`
Commands run twice	Verify `withoutOverlapping()` is configured
Lock conflicts across environments	Use unique cache prefixes per environment

Conclusion

Laravel's mutex and withoutOverlapping() feature is a powerful tool for preventing race conditions in scheduled commands. Understanding how it works helps you:

Debug "Has Mutex" messages
Configure appropriate lock timeouts
Build robust, concurrent-safe commands

Remember: when in doubt, php artisan schedule:clear-cache is your friend.

References

🚀 Build a Todo App API with FastAPI + uv (The Cleanest Way!)

Manish Chaudhary — Fri, 26 Dec 2025 21:04:54 +0000

🚀 Build a FastAPI Todo App the Right Way (Using uv)

Want to build a lightning-fast API without the Python packaging mess?

Let’s build a Todo API using FastAPI — but with a twist: we’ll use uv, the next-gen Python package manager that automates virtual environments, handles dependency resolution, and gets out of your way.

🧩 What is `uv`?

uv is a modern Python package manager that replaces pip and virtualenv with:

🚀 Ultra-fast dependency installation
📦 Automatic virtual environment creation
🧼 Cleaner project setup with zero requirements.txt

It's built in Rust and is ideal for fast, reproducible Python workflows — perfect for APIs, CLI tools, and data apps.

🛠️ Step 1: Set Up the Project

mkdir fastapi-todo && cd fastapi-todo
uv init --app

uv add fastapi --extra standard

🧠 Step 2: Create the Todo Model in `models.py`

from pydantic import BaseModel

class Todo(BaseModel):
    id: int
    title: str
    completed: bool = False

⚙️ Step 3: Build the API in `main.py`

from fastapi import FastAPI, HTTPException
from models import Todo

app = FastAPI()
todos = []

@app.get("/")
def home():
    return {"message": "Welcome to the FastAPI Todo App"}

@app.get("/todos")
def list_todos():
    return todos

@app.post("/todos", status_code=201)
def add_todo(todo: Todo):
    if any(t.id == todo.id for t in todos):
        raise HTTPException(status_code=400, detail="Todo with this ID already exists.")
    todos.append(todo)
    return todo

@app.put("/todos/{todo_id}")
def update(todo_id: int, updated: Todo):
    for i, t in enumerate(todos):
        if t.id == todo_id:
            todos[i] = updated
            return updated
    raise HTTPException(status_code=404, detail="Todo not found")

@app.delete("/todos/{todo_id}")
def delete(todo_id: int):
    global todos
    todos = [t for t in todos if t.id != todo_id]
    return {"message": "Todo deleted"}

🚀 Step 4: Run the Server

uv run fastapi dev

This spins up the app at http://127.0.0.1:8000.
Try out your endpoints using the auto-generated docs at:

👉 http://127.0.0.1:8000/docs

Laravel Tip: Correctly Counting Grouped Results

Manish Chaudhary — Mon, 09 Jun 2025 12:58:27 +0000

Avoid incorrect counts when using groupBy and having in Laravel queries. Here's the right way to get grouped counts.

If you're using groupBy and having in a Laravel query, be careful how you count the results.

🚫 Incorrect Way

$query = User::query()
    ->select('role', DB::raw('count(*) as total'))
    ->groupBy('role')
    ->having('total', '>', 5);

$query->count(); // ❌ This ignores groupBy and having

✅ Correct Way

$query->toBase()
    ->getCountForPagination(); // ✅ Accurate count of grouped results

Using toBase()->getCountForPagination() respects the groupBy and having parts of the query and returns the correct number of grouped records. This is especially useful when paginating grouped results or doing analytics.

How to Deploy FastAPI on Shared Hosting (cPanel)

Manish Chaudhary — Sun, 01 Jun 2025 16:11:05 +0000

Deploying FastAPI on shared hosting using cPanel can be a bit tricky since shared hosting generally supports WSGI applications, while FastAPI is ASGI-based. However, using the right setup and workarounds, you can successfully run FastAPI apps on shared servers.

Prerequisites

A shared hosting account with cPanel access
Python app support in cPanel (usually with Passenger)
Your FastAPI project (a main.py file with an app instance)

I am going to deploy the project in the domain fastapi.manishdev.com. First, let's create a new subdomain. To do that, I am going to follow these steps.

1. Create a Subdomain first.

Go to domains
Click Create a new domain
In the form, fill the correct subdomain name and click save, this will create a new directory (e.g., fastapi.manish.dev)
You will be taken to a list of domains available, which you can see below.

2. Upload the project using ftp or a file manager

These are my two project files that I will be uploading.

Go to the file manager and select your project directory (e.g., fastapi.manish.dev). Then upload your project files. After uploading your project files, the project directory should look like this.

3. Create a Python App in cPanel

Log in to cPanel.
Go to Software > Setup Python App.
Click Create Application and configure:
Choose an Appropriate Python version (e.g., 3.12.10), Set Application root as required (e.g., fastapi.manish.dev), Set Application URL and domain (e.g, fastapi.manish.dev), and click create
Copy the command to access the application’s virtual environment from the place pointed by the arrow, and click Stop App

4. Install dependencies and run FastAPI in the terminal

Open Terminal in cPanel and run these commands one by one.

source /path/to/virtualenv/fastapi.manishdev.com/3.12/bin/activate && cd /path/to/fastapi.manishdev.com

pip install -r requirements.txt

uvicorn main:app --host 0.0.0.0 --port 8001

Paste and run the command you copied in the above step to enable the virtual environment and cd into the project directory. Then install packages with Pip here. Then run Uvicorn with this command.

I am running uvicorn on port 8001 as 8000 is not available, you can use 8000 as well if it's available.

4. Update .htaccess

Lastly, let's add/update the .htaccess file. Copy the content from below and paste it into your .htaccess file located in the project directory.

RewriteEngine On

# Force HTTPS
RewriteCond %{HTTPS} !=on
RewriteRule ^(.*)$ https://%{HTTP_HOST}/$1 [R=301,L]

# Reverse Proxy
RewriteRule ^(.*)$ http://fastapi.manishdev.com:8001/$1 [P,L]

5. Finally when I visit url I get json response as below.

I have created this post taking reference from this blog post from lucidgen

2. Reading CSV Files with Pandas

Manish Chaudhary — Fri, 28 Mar 2025 17:31:40 +0000

Reading CSV Files with Pandas

Pandas is a powerful Python library for data analysis and manipulation. One of the most common tasks in data analysis is reading CSV (Comma-Separated Values) files. Pandas makes this process simple with its read_csv function.

Reading a CSV File

To read a CSV file into a Pandas DataFrame, use the following code:

import pandas as pd

# Read CSV file
df = pd.read_csv("data.csv")

### Display the first five rows
print(df.head())

Handling Different Delimiters

If your CSV file uses a delimiter other than a comma, specify it using the delimiter parameter:

df = pd.read_csv("data.tsv", delimiter="\t")  # Tab-separated file

Reading Large CSV Files

For large files, you can read them in chunks using the chunksize parameter:

chunks = pd.read_csv("large_data.csv", chunksize=1000)
for chunk in chunks:
    print(chunk.head())

Selecting Specific Columns

To load only certain columns, use the usecols parameter:

df = pd.read_csv("data.csv", usecols=["column1", "column2"])

Handling Missing Values

To handle missing values while reading a CSV file, use the na_values parameter:

df = pd.read_csv("data.csv", na_values=["N/A", "na", "--"])

Conclusion

Pandas provides a flexible and efficient way to read CSV files, whether they are small or large, formatted differently, or contain missing values. Mastering read_csv will significantly enhance your data-handling capabilities in Python.

1. Installing Pandas

Manish Chaudhary — Thu, 27 Mar 2025 17:10:15 +0000

Title: How to Install Pandas – A Quick Guide

Pandas is a popular Python library for data analysis. Here’s how to install it quickly.

Prerequisites

Python (version 3.6+): Check with python --version or python3 --version.
Pip: Ensure it's installed using pip --version. If missing, install with python -m ensurepip --default-pip.

Installation Methods

Using Pip (Recommended)

pip install pandas

For Python 3:

pip3 install pandas

In a Virtual Environment

Windows:

python -m venv myenv
myenv\Scripts\activate
pip install pandas

macOS/Linux:

python3 -m venv myenv
source myenv/bin/activate
pip install pandas

Using Conda (For Anaconda Users)

conda install pandas

Verify Installation

Run the following in Python:

import pandas as pd
print(pd.__version__)

Troubleshooting

Command Not Found: Ensure Python/Pip are in PATH.
Permission Errors: Use pip install --user pandas or sudo pip install pandas (macOS/Linux).
Dependency Issues: Use python3 -m pip install pandas to specify Python version.

With Pandas installed, you're ready to explore data! Happy coding!

How to Check if a Word Exists in a Text Using Python

Manish Chaudhary — Sat, 22 Mar 2025 16:02:10 +0000

When working with text data, you often need to check whether a specific word appears in a given text. The Python function below provides a simple way to do this using regular expressions:

import re

def word_in_text(word, text):
    word = word.lower()
    text = text.lower()
    match = re.search(word, text)

    if match:
        return True
    return False

How to run test with coverage with html dashboard

Manish Chaudhary — Thu, 20 Mar 2025 15:41:36 +0000

php artisan test --coverage --coverage-html=coverage-dir

"Please provide a valid cache path" error in laravel

Manish Chaudhary — Wed, 25 Sep 2024 08:47:59 +0000

Run following commands

cd storage/

mkdir -p framework/{sessions,views,cache}

chmod -R 775 framework

Tricks to get process id and terminate it in mac

Manish Chaudhary — Mon, 16 Sep 2024 09:48:05 +0000

To get the process id running the port

lsof -i :port_number

lsof -i :port_number -P -n

To terminate the process

kill PID
kill -9 PID

Some Useful Linux Commands

Manish Chaudhary — Thu, 08 Aug 2024 14:23:14 +0000

Search Specific text in a file

cat filename | grep keyword

Show last few lines in a file

tail -f filename

Shows last couple of lines

tail -100 filename # shows last 100 lines

keeps showing new content if new content gets added

locate to search file

install mlocate package first

locate filename

For queue supervisor

login as root first

supervisorctl status

Note: Location of supervisor configuration files

cd /etc/supervisor/conf.d/ # as this is the location of files

Show List of files

ls

will show list of files with names like worker-xyz.conf

How to fix SQLSTATE[HY000]: General error: 1298 Unknown or incorrect time zone: 'UCT'

Manish Chaudhary — Thu, 01 Aug 2024 12:09:13 +0000

I am in mac and got this issue

When In Laravel

You add timezone key to database.php connections.mysql

Fix

mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql

DEV Community: Manish Chaudhary

Understanding Laravel's Mutex and WithoutOverlapping: Preventing Concurrent Command Execution

Introduction

What is a Mutex?

The withoutOverlapping() Method

Basic Usage

How It Works

Lock Expiration

Common Scenarios and Solutions

Scenario 1: "Has Mutex" When Running Manually

Scenario 2: Command Crashes Mid-Execution

Scenario 3: Running Commands in Multiple Environments

The Isolatable Interface

Running with Isolation Flag

Where Are Mutex Locks Stored?

Manually Clearing File-Based Locks

Best Practices

1. Set Appropriate Lock Expiration

2. Use runInBackground() for Long Commands

3. Add Logging for Debugging

4. Handle Graceful Shutdown

Real-World Example

Troubleshooting Checklist

Conclusion

References

🚀 Build a Todo App API with FastAPI + uv (The Cleanest Way!)

🚀 Build a FastAPI Todo App the Right Way (Using uv)

🧩 What is uv?

🛠️ Step 1: Set Up the Project

🧠 Step 2: Create the Todo Model in models.py

⚙️ Step 3: Build the API in main.py

🚀 Step 4: Run the Server

Laravel Tip: Correctly Counting Grouped Results

🚫 Incorrect Way

✅ Correct Way

How to Deploy FastAPI on Shared Hosting (cPanel)

Prerequisites

1. Create a Subdomain first.

2. Upload the project using ftp or a file manager

3. Create a Python App in cPanel

4. Install dependencies and run FastAPI in the terminal

4. Update .htaccess

5. Finally when I visit url I get json response as below.

2. Reading CSV Files with Pandas

Reading CSV Files with Pandas

Reading a CSV File

Handling Different Delimiters

Reading Large CSV Files

Selecting Specific Columns

Handling Missing Values

Conclusion

1. Installing Pandas

Prerequisites

Installation Methods

Using Pip (Recommended)

In a Virtual Environment

Using Conda (For Anaconda Users)

Verify Installation

Troubleshooting

How to Check if a Word Exists in a Text Using Python

How to run test with coverage with html dashboard

"Please provide a valid cache path" error in laravel

Tricks to get process id and terminate it in mac

To get the process id running the port

To terminate the process

Some Useful Linux Commands

Search Specific text in a file

Show last few lines in a file

Shows last couple of lines

locate to search file

install mlocate package first

For queue supervisor

login as root first

Note: Location of supervisor configuration files

Show List of files

How to fix SQLSTATE[HY000]: General error: 1298 Unknown or incorrect time zone: 'UCT'

When In Laravel

Fix

The `withoutOverlapping()` Method

2. Use `runInBackground()` for Long Commands

🧩 What is `uv`?

🧠 Step 2: Create the Todo Model in `models.py`

⚙️ Step 3: Build the API in `main.py`