Complete Tutorial: Setting Up Laravel Telescope Correctly (Windows + XAMPP + Custom Domain)

This tutorial explains why Telescope was not working, what went wrong, and how to fix it permanently, including all real-world issues you faced like 404 errors, empty .htaccess, Apache misconfiguration, subdomains, and performance tracking.

---

1. What Laravel Telescope Is (and What It Is Not)

Laravel Telescope is not just a debugging tool.
It is a request, query, and performance inspection system that records:

• HTTP requests & responses
• Database queries (including slow queries)
• Exceptions and errors
• Logs
• Jobs, queues, cache, events
• API calls

Important understanding:

• Telescope depends fully on Laravel routing
• If Apache does not forward requests to index.php, Telescope will never load
• A 404 from Apache means Laravel was never reached

This exact thing happened in your case.

---

2. Why You Were Getting 404 on /telescope

Your screenshot clearly showed:

• Apache error page (not Laravel error page)
• URL: http://doc-core-ma/telescope
• Message: The requested URL was not found on this server

This proves:

• Apache was handling the request
• Laravel routes were never executed
• Telescope routes were never registered

Root causes identified:

1. public/.htaccess file was empty
2. Apache rewrite module was not effectively forwarding requests
3. VirtualHost was either missing or incorrectly pointing

---

3. Correct Laravel Folder Structure (Non-Negotiable)

Your project must look like this:

doc-core-ma/
├── app/
├── bootstrap/
├── config/
├── public/
│   ├── index.php
│   ├── .htaccess   ← REQUIRED
├── routes/
├── storage/
├── vendor/

Important rule:

• Apache must point to public/
• Never point Apache to project root

---

4. Installing Telescope (Correct and Safe Way)

From your Laravel project root:

composer require laravel/telescope --dev
php artisan telescope:install
php artisan migrate

This does three things:

1. Registers Telescope service provider
2. Publishes configuration
3. Creates database tables (telescope_entries)

After this, Telescope exists, but it still won’t work unless Apache is correct.

---

5. The .htaccess File (Your Main Missing Piece)

You confirmed that .htaccess was empty.
This alone guarantees 404 for all Laravel routes.

Correct .htaccess content

Location:

C:\xampp\htdocs\doc-core-ma\public\.htaccess

Content (paste exactly):

<IfModule mod_rewrite.c>
    RewriteEngine On

    RewriteCond %{HTTP:Authorization} .
    RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^ index.php [L]
</IfModule>

What this does in plain language:

• Enables URL rewriting
• Sends every request (/telescope, /login, /api/*) to Laravel
• Allows Laravel router to decide what to do

Without this, Laravel is blind.

---

6. Apache Configuration (Most Important Section)

6.1 Enable Rewrite Module

Open:

C:\xampp\apache\conf\httpd.conf

Ensure this line exists and is NOT commented:

LoadModule rewrite_module modules/mod_rewrite.so

If commented, remove #.

---

6.2 Allow .htaccess Overrides

In the same file, find:

<Directory "C:/xampp/htdocs">
    AllowOverride None

Change it to:

<Directory "C:/xampp/htdocs">
    AllowOverride All
    Require all granted
</Directory>

This allows .htaccess to work.

---

7. VirtualHost Configuration (doc-core-ma)

Open:

C:\xampp\apache\conf\extra\httpd-vhosts.conf

Add or fix this block:

<VirtualHost *:80>
    ServerName doc-core-ma
    DocumentRoot "C:/xampp/htdocs/doc-core-ma/public"

    <Directory "C:/xampp/htdocs/doc-core-ma/public">
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog "logs/doc-core-ma-error.log"
    CustomLog "logs/doc-core-ma-access.log" common
</VirtualHost>

Critical points:

• DocumentRoot ends with /public
• AllowOverride All is mandatory
• No Laravel routes will work without this

---

8. Restart Apache (Mandatory)

Changes do nothing until Apache restarts.

From XAMPP:

• Stop Apache
• Start Apache

---

9. Laravel Cache Cleanup (Mandatory)

Run:

php artisan optimize:clear

This clears:

• Config cache
• Route cache
• View cache

Always do this after config or env changes.

---

10. Confirm Telescope Is Enabled

Run:

php artisan telescope:status

If disabled:

php artisan telescope:enable

---

11. Verify Telescope Routes Exist

Run:

php artisan route:list

You must see routes like:

GET|HEAD  telescope
GET|HEAD  telescope/requests
GET|HEAD  telescope/queries

If these exist, Laravel side is correct.

---

12. Accessing Telescope

Now open in browser:

http://doc-core-ma/telescope

You should see:

• Requests
• Queries
• Exceptions
• Logs
• Jobs
• Cache

If this loads, your setup is 100% correct.

---

13. Telescope for Performance Monitoring (Important Settings)

Open:

config/telescope.php

Ensure these watchers are enabled:

'watchers' => [
    Laravel\Telescope\Watchers\RequestWatcher::class => true,

    Laravel\Telescope\Watchers\QueryWatcher::class => [
        'enabled' => true,
        'slow' => 100,
    ],

    Laravel\Telescope\Watchers\ExceptionWatcher::class => true,
    Laravel\Telescope\Watchers\LogWatcher::class => true,
],

This allows you to:

• Detect slow queries
• Measure request time
• Track performance regressions

---

14. Avoiding Common Errors You Faced

Error: Target class [auth.admin] does not exist

Cause:

• Telescope routes loading custom middleware

Fix:
In config/telescope.php, middleware should be:

'middleware' => ['web'],

Never add custom guards here.

---

Error: Telescope works on /telescope but not /hospitals/telescope

Explanation:

• Telescope does not auto-detect subfolders
• You must explicitly configure path

In .env:

TELESCOPE_PATH=hospitals/telescope

Then:

php artisan optimize:clear

---

15. Security Best Practice (Very Important)

Never expose Telescope in production.

In production .env:

TELESCOPE_ENABLED=false

Or restrict access via gate in TelescopeServiceProvider.

---

16. Final Mental Model (Very Important)

Remember this chain:

Browser
→ Apache
→ .htaccess
→ public/index.php
→ Laravel Router
→ Telescope Routes

If any one layer breaks, Telescope fails.

In your case:

• .htaccess was empty
• Apache never reached Laravel
• 404 was expected

---

17. What You Can Do Next (Recommended)

Now that Telescope works, you can:

• Identify slow database queries
• Optimize API endpoints
• Monitor job execution time
• Track errors across microservices
• Combine with Laravel Debugbar and MySQL slow query logs