Technical Report: HTTP 413 Entity Too Large Error in Stellarium Remote Control / Script Editor /Execution error

[kutaibaa-akraa]

Comprehensive Analysis and Solutions for Large Script Execution

---

@gzotti @alex-w @10110111

Report ID: RC-HTTP-413-001
Date: July 18, 2026
Author: kutaibaa-akraa
Related PR: #4956 - Comprehensive Remote Control Enhancement

---

1. Executive Summary

The Stellarium Remote Control plugin, enhanced with the new Script Editor module, enables users to generate and execute complex Stellarium Script (.ssc) files directly from the web interface. However, when attempting to run scripts larger than approximately 15 KB (e.g., constellation tours with 51+ constellations, star tours with hundreds of entries), the server returns HTTP 413 Entity Too Large.

This report documents the root cause, analyzes the server architecture, and provides two concrete solutions:

1. Hardcoded Fix: Modify the default limit in the source code
2. Configurable Fix: Allow users to customize the limit via config.ini

The issue is critical because it prevents the execution of scripts that are essential for educational presentations, sky culture tours, and automated sequences.

---

2. Problem Description

2.1 Observed Behavior

When a user writes or generates a script in the Script Editor and clicks "Run" (Ctrl+Enter):

1. The script code is sent via HTTP POST to /api/scripts/direct
2. The server responds with HTTP 413 Entity Too Large
3. The script fails to execute

2.2 Scripts That Fail

Script Type	Lines	Approx. Size	Result
Arabic (Al-Sufi) Constellations Tour (51 constellations) static array self contained	~284 lines	~12-16 KB	❌ HTTP 413
Modern Constellations Tour (88 constellations) static array self contained	~321 lines	~14-18 KB	❌ HTTP 413
Stars Tour (selected patterns) with large star name array	Variable	Up to 50 KB+	❌ HTTP 413
Short test script (core.debug("test"))	1 line	< 1 KB	Success
Basic object selection script	5-10 lines	~2 KB	Success

Note: The script file size alone does not determine failure. I think URL encoding adds 1-3% overhead. A 11 KB file becomes ~16,435 bytes after encoding, exceeding the 16,384 byte limit by just 51 bytes.

2.3 Console Output

POST http://localhost:8090/api/scripts/direct
Status: 413 entity too large
Content-Length: 16435
Content-Type: application/x-www-form-urlencoded; charset=UTF-8

XML Parsing Error: syntax error
Location: http://localhost:8090/api/scripts/direct
Line Number 1, Column 1

2.4 Error Propagation

XHR POST http://localhost:8090/api/scripts/direct [HTTP/1.1 413 entity too large 5ms]

Error sending command to server: undefined

Stack trace:
  send http://localhost:8090/js/jquery-3.7.1.js:9940:10
  ajax http://localhost:8090/js/jquery-3.7.1.js:9521:15
  postCmd http://localhost:8090/js/api/remotecontrol.js:177:15
  runDirectScript http://localhost:8090/js/api/scripts.js:46:16
  runScript http://localhost:8090/js/scripteditor/scriptEditor.js:794:13

---

3. Root Cause Analysis

3.1 Where Is the Limit Defined?

The HTTP server used by the Remote Control plugin is QtWebApp. The request size limit is defined in HttpConnectionHandlerSettings:

stellarium/plugins/RemoteControl/src/qtwebapp/httpserver/httpconnectionhandler.h

Line 45 in f8564ac

: readTimeout(10000),maxRequestSize(16384),maxMultipartSize(1048576)

// httpconnectionhandler.h - lines 43-71
struct HttpConnectionHandlerSettings {
    HttpConnectionHandlerSettings()
        : readTimeout(10000), maxRequestSize(16384), maxMultipartSize(1048576)
    {}
    // ...
};

• maxRequestSize = 16,384 bytes (16 KB) – This is the limit for standard POST bodies (including application/x-www-form-urlencoded)
• maxMultipartSize = 1,048,576 bytes (1 MB) – This is the limit for multipart/form-data uploads

3.2 Why 16 KB Was Sufficient Previously

The Remote Control plugin was originally designed for:

• Small JSON requests (/api/main/status, parameter changes)
• Short stelssc buttons (single-line script commands)
• Location search with short strings
• Script management (starting/stopping scripts by name, not sending code)

None of these original use cases required sending more than a few hundred bytes. The Script Editor fundamentally changes this by enabling full script code transmission.

3.3 Why Doesn't config.ini Work Currently?

The Remote Control module does not read maxRequestSize or maxMultipartSize from config.ini. Looking at RemoteControl.cpp:

stellarium/plugins/RemoteControl/src/RemoteControl.cpp

Line 308 in f8564ac

void RemoteControl::loadSettings()

void RemoteControl::loadSettings()
{
    conf->beginGroup("RemoteControl");
    setFlagAutoStart(conf->value("autostart", false).toBool());
    setFlagUsePassword(conf->value("use_password", false).toBool());
    setPassword(conf->value("password", "").toString());
    setFlagEnableCors(conf->value("enable_cors", false).toBool());
    setCorsOrigin(conf->value("cors_origin", "").toString());
    setPort(conf->value("port", 8090).toInt());
    minThreads = conf->value("min_threads", 1).toInt();
    maxThreads = conf->value("max_threads", 30).toInt();
    // ⚠️ NO maxRequestSize or maxMultipartSize here!
    conf->endGroup();
}

And in startServer():

stellarium/plugins/RemoteControl/src/RemoteControl.cpp

Line 272 in f8564ac

void RemoteControl::startServer()

void RemoteControl::startServer()
{
    HttpListenerSettings settings;
    settings.port = port;
    settings.minThreads = minThreads;
    settings.maxThreads = maxThreads;
    // ⚠️ NO settings.maxRequestSize or settings.maxMultipartSize here!
    httpListener = new HttpListener(settings, requestHandler);
}

The HttpListenerSettings struct inherits from HttpConnectionHandlerSettings, which contains maxRequestSize and maxMultipartSize, but these fields are never populated from configuration.

---

4. Solution 1: Hardcoded Fix (Simple)

4.1 Description

Modify the default values directly in httpconnectionhandler.h.

4.2 Implementation

stellarium/plugins/RemoteControl/src/qtwebapp/httpserver/httpconnectionhandler.h

Line 45 in f8564ac

: readTimeout(10000),maxRequestSize(16384),maxMultipartSize(1048576)

// httpconnectionhandler.h - lines 43-54
struct HttpConnectionHandlerSettings {
    HttpConnectionHandlerSettings()
        : readTimeout(60000),                    // Increase timeout as well
          maxRequestSize(5242880),               // Change from 16384 to 5 MB
          maxMultipartSize(5242880)              // Change from 1 MB to 5 MB
    {}
    // ...
};

4.3 Advantages

• Single file change – Minimal code modification
• Works immediately after recompilation
• No additional configuration required by users

4.4 Disadvantages

• Hardcoded values – Not user-configurable
• Requires recompilation – Users cannot change the limit without rebuilding
• No flexibility – Same limit for all users

4.5 Recommended Value

Setting	Recommended Value	Rationale
maxRequestSize	5,242,880 (5 MB)	Sufficient for 500+ line scripts
maxMultipartSize	5,242,880 (5 MB)	Consistent with request limit
readTimeout	120,000 (2 min)	Allow time for large script uploads

---

5. Solution 2: Configurable Fix (Recommended)

5.1 Description

Add support for maxRequestSize and maxMultipartSize in config.ini, allowing users to customize the limit without recompilation.

5.2 Implementation Details

Step 1: Add Properties to (RemoteControl.hpp)

// RemoteControl.hpp
Q_PROPERTY(int maxRequestSize
           READ getMaxRequestSize
           WRITE setMaxRequestSize
           NOTIFY maxRequestSizeChanged)

Q_PROPERTY(int maxMultipartSize
           READ getMaxMultipartSize
           WRITE setMaxMultipartSize
           NOTIFY maxMultipartSizeChanged)

public:
    int getMaxRequestSize() const { return maxRequestSize; }
    int getMaxMultipartSize() const { return maxMultipartSize; }
    void setMaxRequestSize(const int size);
    void setMaxMultipartSize(const int size);

signals:
    void maxRequestSizeChanged(int val);
    void maxMultipartSizeChanged(int val);

private:
    int maxRequestSize;
    int maxMultipartSize;

Step 2: Read Settings in (RemoteControl.cpp)

// RemoteControl.cpp Lines 308-320
void RemoteControl::loadSettings()
{
    conf->beginGroup("RemoteControl");
    // ... existing settings ...
    maxRequestSize = conf->value("maxRequestSize", 16384).toInt();
    maxMultipartSize = conf->value("maxMultipartSize", 1048576).toInt();
    conf->endGroup();
}

void RemoteControl::saveSettings()
{
    conf->beginGroup("RemoteControl");
    // ... existing settings ...
    conf->setValue("maxRequestSize", maxRequestSize);
    conf->setValue("maxMultipartSize", maxMultipartSize);
    conf->endGroup();
}

void RemoteControl::setMaxRequestSize(const int size)
{
    if (size != maxRequestSize)
    {
        maxRequestSize = size;
        emit maxRequestSizeChanged(size);
        if (httpListener)
        {
            stopServer();
            startServer();
        }
    }
}

void RemoteControl::setMaxMultipartSize(const int size)
{
    if (size != maxMultipartSize)
    {
        maxMultipartSize = size;
        emit maxMultipartSizeChanged(size);
        if (httpListener)
        {
            stopServer();
            startServer();
        }
    }
}

Step 3: Apply Settings in startServer()

(RemoteControl.cpp)

// RemoteControl.cpp Lines 272-286
void RemoteControl::startServer()
{
    HttpListenerSettings settings;
    settings.port = port;
    settings.minThreads = minThreads;
    settings.maxThreads = maxThreads;
    settings.maxRequestSize = maxRequestSize;      // ← NEW
    settings.maxMultipartSize = maxMultipartSize;  // ← NEW
    httpListener = new HttpListener(settings, requestHandler);
}

Step 4: User Configuration

Users can then add to config.ini:

[RemoteControl]
autostart                                 = true
cors_origin                               = *
enable_cors                               = true
maxMultipartSize                          = 5242880
maxRequestSize                            = 5242880
max_threads                               = 30
min_threads                               = 1
port                                      = 8090
readTimeout                               = 60000
use_password                              = false

5.3 Advantages

• User-configurable – Users can adjust limits based on their needs
• No recompilation required – Just edit config.ini and restart
• Flexible – Different users can have different limits
• Future-proof – Easy to adjust if requirements change

5.4 Disadvantages

• More code changes – Requires modification of 2-3 files
• Potential misuse – Users could set excessively high values

5.5 Recommended Default Values

Setting	Default Value	Rationale
maxRequestSize	5,242,880 (5 MB)	Sufficient for 99% of scripts
maxMultipartSize	5,242,880 (5 MB)	Consistent with request limit

---

6. Recommendation

6.1 Immediate Action (For PR #4956)

Implement Solution 2 (Configurable Fix) as the primary approach.

Provides maximum flexibility for users, Allows different configurations for different use cases

6.2 Testing Recommendations

After implementation, test with:

1. Arabic (Al-Sufi) Constellations Tour – 51 constellations, ~284 lines
2. Modern Constellations Tour – 88 constellations, ~321 lines
3. Custom large script – 1000+ lines, > 50 KB
4. Concurrent large scripts – Multiple users sending large scripts simultaneously

---

7. Impact on Related Modules

7.1 Script Editor

• Will be able to run large scripts without errors
• User experience will be seamless

7.2 Sky Culture Tour Generator

• Constellation tours (51-88 constellations) will execute properly
• Large star tours & other large user scripts will work

8. Conclusion

The HTTP 413 Entity Too Large error is a critical blocker for the Script Editor that I intending to test. The default 16 KB limit in QtWebApp is insufficient for scripts that are now being generated by the Sky Culture Tour Generator and other tools.

The solution is straightforward: either increase the default limit (Hardcoded Fix) or add user-configurable support (Configurable Fix). Both are simple to implement and have minimal risk.

The Configurable Fix (Solution 2) is very recommended because it provides the best user experience and future flexibility.

---

9. References

Related Code Files

File	Purpose
httpconnectionhandler.h	Defines maxRequestSize (16 KB default)
httpconnectionhandler.cpp	Implements request size validation
httprequest.cpp	Reads request body, checks size limits
RemoteControl.cpp	Loads settings, starts HTTP listener
ScriptService.cpp	Handles /api/scripts/direct POST requests

Related Issues

• PR #4956 - Comprehensive Remote Control Enhancement

[gzotti]

Hear, hear. The 'direct' API has been designed for rapid execution of 1-5 line scripts that one can assign to a RC GUI button. Longer scripts, those that usually take weeks to develop, usually come as stored files for which 'run' is the API to call for execution.
The 'direct' call may be used by various other projects as well. Can you guarantee that there will be no adverse effects? (slowdown, other weird issues?)

[kutaibaa-akraa]

@gzotti
Dr Georg, you raise a valid concern about performance.

I want to be honest: I cannot guarantee zero performance impact without thorough testing. However, I believe the risk is manageable because:

• This is opt-in, not mandatory – The default remains 16 KB. Users must explicitly add maxRequestSize to their config.ini to change it. This means users who don't need larger scripts see no change whatsoever.

• Real scripts already exceed the limit – The 284-line Arabic Constellations Tour and the 321-line Modern Constellations Tour (both ~14-18 KB) are legitimate educational scripts that already fail. This is not a theoretical issue – it's blocking real functionality that people want to use.

• Limited practical impact – Large scripts are sent once, not repeatedly. The server already handles JSON responses of similar size via /api/main/status.

• Conservative and fair limits – I propose setting maxRequestSize to 500 KB (512,000 bytes) as the configurable limit. This is sufficient for 99% of scripts while remaining well below the 1 MB maxMultipartSize limit (which we keep unchanged). This ensures:

  • All constellation tours (51-88 constellations, ~16-18 KB) work seamlessly
  • Even large star tours (hundreds of entries) are accommodated
  • The server is not burdened with excessively large requests

• Risk mitigation – If you're concerned, we can:

  • Conduct performance benchmarks before merging
  • Add a warning in the documentation about potential impacts
  • Keep maxMultipartSize at its default 1 MB, which is already sufficient for file uploads

Bottom line: 500 KB is a fair, conservative limit that solves the immediate problem without introducing unnecessary risk. Users who need more can adjust, but for the vast majority, 500 KB will be more than enough.

---

[kutaibaa-akraa]

Any Idea ?

[gzotti]

You are flooding us with just way too much code and text to read. My spare time is limited! We should probably first review and fix issues with your open PR, then accept that, and then continue here.

General question: there is a semi-automatic self explanatory API project called OpenAPI. Would that be useful from a user perspective, and would it reduce maintainer burden for future API changes? Please respond as human, not just another LLM answer.

[kutaibaa-akraa]

I haven't looked into the OpenAPI project you mentioned before. From what little I've seen from the documentaion, it does resemble what I've been building manually with apiExplorer.js and codeGenerator.js , but I need proper time to study it and evaluate it properly before forming any conclusions.
I really newbie with OpenApi project, but sounds good