add documentation site with markdown rendering (M12)
This commit is contained in:
469
portal/internal/web/docs/troubleshooting.md
Normal file
469
portal/internal/web/docs/troubleshooting.md
Normal file
@@ -0,0 +1,469 @@
|
||||
# Troubleshooting
|
||||
|
||||
Solutions for common issues when developing Mosis apps.
|
||||
|
||||
## Build Errors
|
||||
|
||||
### "Invalid manifest: missing required field"
|
||||
|
||||
Your `manifest.json` is missing a required field.
|
||||
|
||||
**Solution:** Check these required fields:
|
||||
```json
|
||||
{
|
||||
"id": "com.example.app",
|
||||
"name": "App Name",
|
||||
"version": "1.0.0",
|
||||
"version_code": 1,
|
||||
"entry": "assets/main.rml",
|
||||
"author": {
|
||||
"name": "Your Name",
|
||||
"email": "you@example.com"
|
||||
},
|
||||
"icons": {
|
||||
"128": "icon.png"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### "Invalid package ID format"
|
||||
|
||||
Package IDs must follow reverse domain notation.
|
||||
|
||||
**Valid:**
|
||||
- `com.example.myapp`
|
||||
- `com.yourname.calculator`
|
||||
- `io.github.user.app`
|
||||
|
||||
**Invalid:**
|
||||
- `myapp` (needs domain prefix)
|
||||
- `Com.Example.App` (must be lowercase)
|
||||
- `com..app` (no double dots)
|
||||
- `com.app.` (can't end with dot)
|
||||
|
||||
### "Entry point not found"
|
||||
|
||||
The `entry` file specified in manifest doesn't exist.
|
||||
|
||||
**Solution:** Verify the path:
|
||||
```json
|
||||
"entry": "assets/main.rml"
|
||||
```
|
||||
|
||||
Check that `assets/main.rml` exists relative to your manifest file.
|
||||
|
||||
### "Icon not found"
|
||||
|
||||
An icon file specified in manifest doesn't exist.
|
||||
|
||||
**Solution:**
|
||||
1. Check file paths are correct
|
||||
2. Ensure files exist
|
||||
3. Use forward slashes in paths
|
||||
|
||||
```json
|
||||
"icons": {
|
||||
"128": "icons/icon-128.png"
|
||||
}
|
||||
```
|
||||
|
||||
### "Package too large"
|
||||
|
||||
Package exceeds the 10MB limit.
|
||||
|
||||
**Solutions:**
|
||||
- Compress images (use TGA or optimized PNG)
|
||||
- Remove unused assets
|
||||
- Move large files to external CDN
|
||||
- Check for accidentally included files
|
||||
|
||||
## Runtime Errors
|
||||
|
||||
### "attempt to index nil value"
|
||||
|
||||
You're accessing a property on a nil variable.
|
||||
|
||||
**Common causes:**
|
||||
|
||||
1. **Element not found:**
|
||||
```lua
|
||||
-- Bad
|
||||
local elem = document:GetElementById("typo")
|
||||
elem.inner_rml = "Hello" -- Error: elem is nil
|
||||
|
||||
-- Good
|
||||
local elem = document:GetElementById("correct-id")
|
||||
if elem then
|
||||
elem.inner_rml = "Hello"
|
||||
end
|
||||
```
|
||||
|
||||
2. **Table key doesn't exist:**
|
||||
```lua
|
||||
-- Bad
|
||||
local data = json.decode(response.body)
|
||||
print(data.user.name) -- Error if user is nil
|
||||
|
||||
-- Good
|
||||
if data and data.user then
|
||||
print(data.user.name)
|
||||
end
|
||||
```
|
||||
|
||||
### "attempt to call nil value"
|
||||
|
||||
You're calling a function that doesn't exist.
|
||||
|
||||
**Common causes:**
|
||||
|
||||
1. **Typo in function name:**
|
||||
```lua
|
||||
-- Bad: navigateto (lowercase t)
|
||||
navigateto("settings")
|
||||
|
||||
-- Good
|
||||
navigateTo("settings")
|
||||
```
|
||||
|
||||
2. **Missing permission:**
|
||||
```lua
|
||||
-- Error if 'network' permission not declared
|
||||
http.get(url, callback)
|
||||
```
|
||||
|
||||
### "Permission denied"
|
||||
|
||||
You're using an API without the required permission.
|
||||
|
||||
**Solution:** Add permission to manifest:
|
||||
```json
|
||||
"permissions": ["storage", "network"]
|
||||
```
|
||||
|
||||
### "Network request failed"
|
||||
|
||||
HTTP request couldn't complete.
|
||||
|
||||
**Common causes:**
|
||||
|
||||
1. **No network permission:**
|
||||
```json
|
||||
"permissions": ["network"]
|
||||
```
|
||||
|
||||
2. **Invalid URL:**
|
||||
```lua
|
||||
-- Bad: missing protocol
|
||||
http.get("api.example.com/data", callback)
|
||||
|
||||
-- Good
|
||||
http.get("https://api.example.com/data", callback)
|
||||
```
|
||||
|
||||
3. **HTTP not allowed (HTTPS only):**
|
||||
```lua
|
||||
-- Bad
|
||||
http.get("http://example.com/data", callback)
|
||||
|
||||
-- Good
|
||||
http.get("https://example.com/data", callback)
|
||||
```
|
||||
|
||||
4. **CORS error:** The server doesn't allow cross-origin requests. Contact the API provider or use a CORS proxy.
|
||||
|
||||
### "Storage quota exceeded"
|
||||
|
||||
You've exceeded the 5MB storage limit.
|
||||
|
||||
**Solution:**
|
||||
- Clear unnecessary data: `storage.clear()`
|
||||
- Use selective removal: `storage.remove("large-key")`
|
||||
- Store only essential data
|
||||
- Consider using network storage for large data
|
||||
|
||||
## UI Issues
|
||||
|
||||
### Element not displaying
|
||||
|
||||
**Check:**
|
||||
|
||||
1. **Display not set to none:**
|
||||
```css
|
||||
/* Element might be hidden */
|
||||
.element {
|
||||
display: none; /* Remove this */
|
||||
}
|
||||
```
|
||||
|
||||
2. **Size is zero:**
|
||||
```css
|
||||
.element {
|
||||
width: 0; /* Add dimensions */
|
||||
height: 0;
|
||||
}
|
||||
```
|
||||
|
||||
3. **Element is off-screen:**
|
||||
```css
|
||||
.element {
|
||||
position: absolute;
|
||||
left: -1000dp; /* Move to visible area */
|
||||
}
|
||||
```
|
||||
|
||||
4. **Z-index issues:**
|
||||
```css
|
||||
.element {
|
||||
z-index: 1; /* Bring to front */
|
||||
}
|
||||
```
|
||||
|
||||
### Click events not working
|
||||
|
||||
**Check:**
|
||||
|
||||
1. **Function exists:**
|
||||
```xml
|
||||
<button onclick="handleClick()">Click</button>
|
||||
```
|
||||
```lua
|
||||
-- Make sure function is defined
|
||||
function handleClick()
|
||||
print("Clicked!")
|
||||
end
|
||||
```
|
||||
|
||||
2. **Element is overlapped:**
|
||||
Another element might be blocking clicks. Check z-index and position.
|
||||
|
||||
3. **Element has pointer-events: none:**
|
||||
```css
|
||||
.element {
|
||||
/* Remove this */
|
||||
pointer-events: none;
|
||||
}
|
||||
```
|
||||
|
||||
### Styles not applying
|
||||
|
||||
**Check:**
|
||||
|
||||
1. **Stylesheet is linked:**
|
||||
```xml
|
||||
<head>
|
||||
<link type="text/rcss" href="styles.rcss"/>
|
||||
</head>
|
||||
```
|
||||
|
||||
2. **Selector is correct:**
|
||||
```css
|
||||
/* Class selector needs dot */
|
||||
.my-class { }
|
||||
|
||||
/* ID selector needs hash */
|
||||
#my-id { }
|
||||
|
||||
/* Tag selector has no prefix */
|
||||
button { }
|
||||
```
|
||||
|
||||
3. **Specificity issues:**
|
||||
More specific selectors override less specific ones:
|
||||
```css
|
||||
/* Less specific */
|
||||
button { color: blue; }
|
||||
|
||||
/* More specific - wins */
|
||||
.btn.primary { color: red; }
|
||||
```
|
||||
|
||||
4. **Units are correct:**
|
||||
```css
|
||||
/* Use dp units */
|
||||
padding: 12dp;
|
||||
|
||||
/* Not px on mobile */
|
||||
padding: 12px; /* May not work correctly */
|
||||
```
|
||||
|
||||
### Layout breaks on different screens
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Use dp units instead of px:**
|
||||
```css
|
||||
padding: 16dp; /* Scales properly */
|
||||
```
|
||||
|
||||
2. **Use flexbox:**
|
||||
```css
|
||||
.container {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
}
|
||||
```
|
||||
|
||||
3. **Use percentage widths:**
|
||||
```css
|
||||
.card {
|
||||
width: 90%;
|
||||
max-width: 400dp;
|
||||
}
|
||||
```
|
||||
|
||||
### Text is cut off
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Allow wrapping:**
|
||||
```css
|
||||
.text {
|
||||
word-break: break-word;
|
||||
}
|
||||
```
|
||||
|
||||
2. **Add overflow scrolling:**
|
||||
```css
|
||||
.container {
|
||||
overflow: auto;
|
||||
}
|
||||
```
|
||||
|
||||
3. **Use ellipsis (if supported):**
|
||||
```css
|
||||
.text {
|
||||
text-overflow: ellipsis;
|
||||
overflow: hidden;
|
||||
white-space: nowrap;
|
||||
}
|
||||
```
|
||||
|
||||
## Designer Issues
|
||||
|
||||
### Hot reload not working
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Save the file** - Changes only reload on save
|
||||
2. **Check file is in watch path**
|
||||
3. **Restart designer** - Sometimes needed after many changes
|
||||
4. **Check for syntax errors** - Invalid files may not reload
|
||||
|
||||
### Designer crashes on startup
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Check file paths:**
|
||||
```bash
|
||||
# Make sure path exists
|
||||
mosis-designer.exe ../assets/main.rml
|
||||
```
|
||||
|
||||
2. **Try a simple file first:**
|
||||
```xml
|
||||
<rml>
|
||||
<head><title>Test</title></head>
|
||||
<body><p>Hello</p></body>
|
||||
</rml>
|
||||
```
|
||||
|
||||
3. **Check for missing assets:**
|
||||
Images or fonts that don't exist can cause crashes.
|
||||
|
||||
4. **Update graphics drivers:**
|
||||
The designer uses OpenGL which requires up-to-date drivers.
|
||||
|
||||
### Rendering looks different on device
|
||||
|
||||
**Common causes:**
|
||||
|
||||
1. **Font differences** - Ensure fonts are bundled
|
||||
2. **DPI scaling** - Use dp units consistently
|
||||
3. **Color profiles** - Use standard sRGB colors
|
||||
|
||||
## Submission Issues
|
||||
|
||||
### "Version code must be higher"
|
||||
|
||||
Each new version needs a higher version_code.
|
||||
|
||||
**Solution:**
|
||||
```json
|
||||
{
|
||||
"version": "1.0.1",
|
||||
"version_code": 2 // Increment from previous
|
||||
}
|
||||
```
|
||||
|
||||
### "Signature verification failed"
|
||||
|
||||
Your package signature is invalid.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Rebuild the package:**
|
||||
```bash
|
||||
mosis build
|
||||
```
|
||||
|
||||
2. **Check signing key is registered:**
|
||||
```bash
|
||||
mosis keys list
|
||||
```
|
||||
|
||||
3. **Re-register your key if needed:**
|
||||
```bash
|
||||
mosis keys register ~/.mosis/keys/production.pub
|
||||
```
|
||||
|
||||
### "Review rejected"
|
||||
|
||||
Check the rejection reason in your dashboard. Common issues:
|
||||
|
||||
| Reason | Solution |
|
||||
|--------|----------|
|
||||
| Inappropriate content | Remove violating content |
|
||||
| Misleading description | Update description to match functionality |
|
||||
| Crashes on launch | Fix startup errors |
|
||||
| Missing privacy policy | Add privacy policy for data-collecting apps |
|
||||
| Impersonation | Don't copy other apps |
|
||||
|
||||
## Getting More Help
|
||||
|
||||
### Check Logs
|
||||
|
||||
**Designer logs:**
|
||||
```bash
|
||||
mosis-designer.exe app.rml --log debug.log
|
||||
```
|
||||
|
||||
**Lua errors:**
|
||||
```lua
|
||||
-- Add error handling
|
||||
local success, err = pcall(function()
|
||||
-- Your code
|
||||
end)
|
||||
if not success then
|
||||
print("Error:", err)
|
||||
end
|
||||
```
|
||||
|
||||
### Search Issues
|
||||
|
||||
Check if others have encountered the same issue:
|
||||
- Developer forum
|
||||
- GitHub issues
|
||||
- Stack Overflow (tag: mosis)
|
||||
|
||||
### Contact Support
|
||||
|
||||
If you're still stuck:
|
||||
1. Gather error messages and logs
|
||||
2. Create minimal reproduction case
|
||||
3. Submit through developer portal support
|
||||
|
||||
## See Also
|
||||
|
||||
- [FAQ](faq.md) - Frequently asked questions
|
||||
- [Lua API Reference](api/lua-api.md) - API documentation
|
||||
- [UI Design Guide](guides/ui-design.md) - Styling reference
|
||||
Reference in New Issue
Block a user