# How to Debug Issues in the Stremio-Web Application: A Complete Developer Guide

> Debug stremio-web application issues effectively. Learn to use browser consoles React DevTools environment variables and network monitoring to find and fix bugs fast.

- Repository: [Stremio/stremio-web](https://github.com/Stremio/stremio-web)
- Tags: how-to-guide
- Published: 2026-05-23

---

**To debug issues in the Stremio-Web application, use the browser console for runtime JavaScript errors, React DevTools for component inspection, and enable verbose logging via environment variables in [`src/services/Chromecast/ChromecastTransport.js`](https://github.com/Stremio/stremio-web/blob/main/src/services/Chromecast/ChromecastTransport.js) while monitoring network requests through the browser's Network tab.**

Stremio-Web is a modern React single-page application (SPA) that runs inside the browser as part of the Stremio media ecosystem. Understanding how to effectively debug issues in the Stremio-Web application requires familiarity with its context-based architecture, centralized error reporting via Sentry, and service worker integration. This guide provides practical techniques based on the actual source code in the `Stremio/stremio-web` repository.

## Core Architecture and Entry Points

Understanding the bootstrap sequence is essential before debugging. The application initializes in [`src/index.js`](https://github.com/Stremio/stremio-web/blob/main/src/index.js), which configures Sentry error reporting, sets up internationalization (i18n), registers the service worker, and mounts the root component inside `React.StrictMode`.

Key architectural components include:

- **CoreProvider** ([`src/core/index.js`](https://github.com/Stremio/stremio-web/blob/main/src/core/index.js)) – Injects the Stremio core (backend bridge) into React context for all downstream components
- **PlatformProvider** ([`src/common/PlatformProvider.js`](https://github.com/Stremio/stremio-web/blob/main/src/common/PlatformProvider.js)) and **FileDropProvider** ([`src/common/FileDropProvider.js`](https://github.com/Stremio/stremio-web/blob/main/src/common/FileDropProvider.js)) – Expose platform-specific APIs for Chromecast and drag-and-drop functionality
- **Router** ([`src/router/Router/index.js`](https://github.com/Stremio/stremio-web/blob/main/src/router/Router/index.js)) – Centralized routing logic that determines which view to render based on URL patterns defined in [`src/router/Router/routeConfigForPath.js`](https://github.com/Stremio/stremio-web/blob/main/src/router/Router/routeConfigForPath.js) and [`src/router/Router/urlParamsForPath.js`](https://github.com/Stremio/stremio-web/blob/main/src/router/Router/urlParamsForPath.js)
- **Services** ([`src/services/Chromecast/Chromecast.js`](https://github.com/Stremio/stremio-web/blob/main/src/services/Chromecast/Chromecast.js)) – Wrappers around external APIs including Chromecast integration
- **Common Hooks** ([`src/common/useStreamingServer.js`](https://github.com/Stremio/stremio-web/blob/main/src/common/useStreamingServer.js), [`src/common/useNotifications.js`](https://github.com/Stremio/stremio-web/blob/main/src/common/useNotifications.js)) – Reusable React hooks for state management and networking

## Debugging Runtime JavaScript Errors

**Browser Console Monitoring**: Open the browser's developer console to view uncaught exceptions. The Sentry initialization block at the top of [`src/index.js`](https://github.com/Stremio/stremio-web/blob/main/src/index.js) captures errors globally, so verify that `SENTRY_DSN` is set in your environment if errors are not being reported.

**Sentry Payload Inspection**: To inspect what data Sentry collects before transmission, configure the scope after initialization:

```javascript
// src/index.js (after Sentry.init)
Sentry.configureScope(scope => {
    scope.setTag('environment', process.env.NODE_ENV);
    console.debug('Sentry scope configured:', scope);
});

```

## Debugging Component Rendering Issues

**React DevTools**: Since the entire application runs under `React.StrictMode`, use the React DevTools browser extension to inspect the component tree, examine props and state, and identify why specific views like [`src/routes/Library/Library.js`](https://github.com/Stremio/stremio-web/blob/main/src/routes/Library/Library.js) might fail to render.

**Error Boundaries**: For development environments, wrap routes with a custom error boundary to isolate UI crashes:

```javascript
// src/common/ErrorBoundary.js
import React from 'react';

export class ErrorBoundary extends React.Component {
    state = { hasError: false, error: null };

    static getDerivedStateFromError(error) {
        return { hasError: true, error };
    }

    componentDidCatch(error, info) {
        console.error('ErrorBoundary caught:', error, info);
    }

    render() {
        if (this.state.hasError) {
            return <div>Something went wrong: {this.state.error.message}</div>;
        }
        return this.props.children;
    }
}

```

Implement the boundary in [`src/App/App.js`](https://github.com/Stremio/stremio-web/blob/main/src/App/App.js):

```javascript
// src/App/App.js
import { ErrorBoundary } from '../common/ErrorBoundary';

function App() {
    return (
        <ErrorBoundary>
            {/* existing router view */}
            <Routes />
        </ErrorBoundary>
    );
}

```

## Debugging Routing and URL Mismatches

When routes fail to resolve or URL parameters parse incorrectly, examine the router configuration in [`src/router/Router/routeConfigForPath.js`](https://github.com/Stremio/stremio-web/blob/main/src/router/Router/routeConfigForPath.js) and the URL parser in [`src/router/Router/urlParamsForPath.js`](https://github.com/Stremio/stremio-web/blob/main/src/router/Router/urlParamsForPath.js). The central router logic in [`src/router/Router/index.js`](https://github.com/Stremio/stremio-web/blob/main/src/router/Router/index.js) uses these files to map paths to specific view components like the Library or Video player.

## Debugging Service Worker Registration Failures

Service worker issues typically manifest as caching problems or failed updates. The registration code lives in [`src/index.js`](https://github.com/Stremio/stremio-web/blob/main/src/index.js) within the service-worker registration block. Check the `catch` block in this file for specific error messages if the worker fails to register.

To force a service worker reload during development:

```javascript
// src/index.js
if (navigator.serviceWorker?.controller) {
    navigator.serviceWorker.controller.postMessage({ type: 'skipWaiting' });
    console.info('Service worker skipWaiting message sent');
}

```

## Debugging Network Requests

Monitor network traffic in the browser's Network tab, filtering by endpoints like `/api/addons`. The [`src/common/useStreamingServer.js`](https://github.com/Stremio/stremio-web/blob/main/src/common/useStreamingServer.js) hook handles streaming server communications, while various files in `src/services/` manage external API calls. Inspect these files to verify request construction and response handling.

## Debugging Chromecast Integration

Chromecast transport logs are controlled via environment variables in [`src/services/Chromecast/ChromecastTransport.js`](https://github.com/Stremio/stremio-web/blob/main/src/services/Chromecast/ChromecastTransport.js). Enable verbose logging by setting `CHROMECAST_DEBUG=true`:

```javascript
// src/services/Chromecast/ChromecastTransport.js
const DEBUG = process.env.CHROMECAST_DEBUG === 'true';
if (DEBUG) {
    console.info('Chromecast transport debug enabled');
}

```

The main integration point is [`src/services/Chromecast/Chromecast.js`](https://github.com/Stremio/stremio-web/blob/main/src/services/Chromecast/Chromecast.js), which coordinates with the transport layer.

## Debugging Internationalization (i18n) Issues

Translation resources are built from `stremio-translations` in the i18n initialization block of [`src/index.js`](https://github.com/Stremio/stremio-web/blob/main/src/index.js). If text fails to appear or displays keys instead of values, verify that resources are loading correctly in the network tab and that the initialization logic executed without errors.

## Debugging Performance Bottlenecks

Use the browser's Performance tab to identify long-running tasks in the React Scheduler. UI-heavy components like `Video` and `Library` utilize `useAnimationFrame` from [`src/common/useAnimationFrame.js`](https://github.com/Stremio/stremio-web/blob/main/src/common/useAnimationFrame.js) for smooth animations. Check this hook's implementation if you encounter jank or high CPU usage during animations.

## Summary

- **Monitor [`src/index.js`](https://github.com/Stremio/stremio-web/blob/main/src/index.js)** – This file controls Sentry initialization, i18n setup, and service worker registration, making it the first place to check for bootstrap failures
- **Use React DevTools** – Essential for inspecting the component hierarchy and context providers like `CoreProvider` and `PlatformProvider`
- **Enable environment-specific logging** – Set `CHROMECAST_DEBUG=true` to troubleshoot casting issues and use `Sentry.configureScope` to verify error reporting
- **Inspect router configuration** – Check [`src/router/Router/routeConfigForPath.js`](https://github.com/Stremio/stremio-web/blob/main/src/router/Router/routeConfigForPath.js) and [`urlParamsForPath.js`](https://github.com/Stremio/stremio-web/blob/main/urlParamsForPath.js) when URLs fail to resolve correctly
- **Wrap components with ErrorBoundary** – Prevent total UI crashes during development by catching errors in React components
- **Check service worker status** – Use the `skipWaiting` message pattern to bypass caching issues during active development

## Frequently Asked Questions

### How do I enable Chromecast debugging in Stremio-Web?

Set the environment variable `CHROMECAST_DEBUG` to `true` before building. In [`src/services/Chromecast/ChromecastTransport.js`](https://github.com/Stremio/stremio-web/blob/main/src/services/Chromecast/ChromecastTransport.js), this variable triggers console logging in the transport layer, allowing you to see communication between the browser and cast devices. Rebuild the application after setting the variable, then open the browser console to view the debug messages.

### Where are runtime JavaScript errors logged in Stremio-Web?

Runtime errors are logged to the browser console and sent to Sentry if the `SENTRY_DSN` environment variable is configured. The Sentry initialization occurs in [`src/index.js`](https://github.com/Stremio/stremio-web/blob/main/src/index.js), and you can enhance logging by adding `Sentry.configureScope` calls to tag errors with specific environment details before they are transmitted.

### How can I force a service worker update during debugging?

Send a `skipWaiting` message to the active service worker controller. In [`src/index.js`](https://github.com/Stremio/stremio-web/blob/main/src/index.js), check for `navigator.serviceWorker.controller` and post a message with `{ type: 'skipWaiting' }`. This immediately activates the waiting service worker, bypassing the standard lifecycle and clearing cached assets that might be causing stale code execution.

### Why might React components fail to render in Stremio-Web?

Rendering failures typically stem from uncaught errors in the component tree or missing context providers. Since the app uses `React.StrictMode`, check the console for warnings about deprecated patterns. Use the ErrorBoundary pattern shown in [`src/common/ErrorBoundary.js`](https://github.com/Stremio/stremio-web/blob/main/src/common/ErrorBoundary.js) to isolate crashes, and verify that `CoreProvider` in [`src/core/index.js`](https://github.com/Stremio/stremio-web/blob/main/src/core/index.js) is properly mounted above the component hierarchy.