Troubleshooting¶
This section covers common issues you might encounter when working with Terra Draw and their solutions.
Common Issues and Solutions¶
1. Import/Module Issues¶
Problem: Terra Draw modules not importing correctly
Solution:
// ESM imports (recommended for Vite/modern bundlers)
import { TerraDraw } from 'terra-draw';
import { TerraDrawMapLibreGLAdapter } from 'terra-draw-maplibre-gl-adapter';
import { TerraDrawPointMode, TerraDrawPolygonMode } from 'terra-draw';
// CommonJS (if needed for older Node.js environments)
const { TerraDraw } = require('terra-draw');
2. Map Not Showing Drawings¶
Problem: Features drawn but not visible on map
Solutions:
// Ensure map is loaded before initializing Terra Draw
map.on('load', () => {
const draw = new TerraDraw({
adapter: new TerraDrawMapLibreGLAdapter({ map }),
modes: [new TerraDrawPointMode()]
});
draw.start(); // Don't forget to start!
});
// Check if adapter is correctly initialized
if (draw.adapter) {
console.log('Adapter initialized successfully');
} else {
console.error('Adapter initialization failed');
}
3. Styling Not Applied¶
Problem: Custom styles not appearing
Solution:
// Ensure styles are in correct format
const mode = new TerraDrawPolygonMode({
styles: {
fillColor: '#FF0000', // Use hex format
outlineColor: '#00FF00', // Not CSS color names
outlineWidth: 2 // Use numbers, not strings
}
});
// Check for typos in style property names
// ✓ Correct: fillColor, outlineColor, pointColor
// ✗ Wrong: fill-color, outline-color, point-color
4. Events Not Firing¶
Problem: Event listeners not triggering
Solution:
// Add event listeners after draw.start()
draw.start();
draw.on('draw', (event) => {
console.log('Feature drawn:', event);
});
// Check event names are correct
// ✓ Correct: 'draw', 'change', 'select', 'deselect', 'mode'
// ✗ Wrong: 'drawn', 'changed', 'selected', 'deselected'
// Ensure proper TypeScript types if using TypeScript
draw.on('change', (event: any) => {
// Handle event
});
5. Performance Issues¶
Problem: Slow performance with many features
Solutions:
// Use coordinate precision to reduce data size
const adapter = new TerraDrawMapLibreGLAdapter({
map,
coordinatePrecision: 6 // Default is higher precision
});
// Debounce change events
let timeout: number;
draw.on('change', () => {
clearTimeout(timeout);
timeout = setTimeout(() => {
updateUI();
}, 100);
});
// Clear unused features periodically
const features = draw.getSnapshot();
if (features.length > 1000) {
// Remove older features
const oldFeatureIds = features.slice(0, -500).map(f => f.id).filter(Boolean);
draw.removeFeatures(oldFeatureIds);
}
6. TypeScript Errors¶
Problem: TypeScript compilation errors
Solutions:
// Install type definitions
npm install --save-dev @types/geojson
// Use proper type assertions
const features = draw.getSnapshot() as GeoJSON.Feature[];
// Define proper interfaces
interface TerraDrrawFeatureProperties {
mode: string;
[key: string]: any;
}
// Handle optional properties
const featureId = feature.id ?? 'unknown';
7. Vite Build Issues¶
Problem: Build fails with Vite
Solutions:
// Add to vite.config.ts if needed
export default {
define: {
global: 'globalThis',
},
optimizeDeps: {
include: ['terra-draw', 'maplibre-gl']
}
};
// For Node.js polyfills (if required)
npm install --save-dev @types/node
8. Mode Not Working¶
Problem: Specific drawing modes not functioning
Solutions:
// Ensure mode is properly imported and instantiated
import { TerraDrawRectangleMode } from 'terra-draw';
const draw = new TerraDraw({
adapter: new TerraDrawMapLibreGLAdapter({ map }),
modes: [
new TerraDrawRectangleMode(), // Create instance with 'new'
new TerraDrawSelectMode()
]
});
// Check mode is available
const availableModes = draw.getMode();
console.log('Available modes:', availableModes);
9. Feature Selection Issues¶
Problem: Cannot select or edit features
Solutions:
// Ensure SelectMode is included
const draw = new TerraDraw({
adapter: new TerraDrawMapLibreGLAdapter({ map }),
modes: [
new TerraDrawPointMode(),
new TerraDrawSelectMode() // Required for selection
]
});
// Switch to select mode
draw.setMode('select');
// Check if features are selectable
const selectMode = new TerraDrawSelectMode({
flags: {
arbitary: {
feature: {
draggable: true,
rotateable: true,
scaleable: true
}
}
}
});
10. Map Library Integration Issues¶
Problem: Adapter not working with specific map library version
Solutions:
// Check compatibility
// MapLibre GL JS: v4, v5 supported
// Leaflet: v1.x supported
// OpenLayers: v10 supported
// Install correct versions
npm install maplibre-gl@^4.7.0
npm install terra-draw-maplibre-gl-adapter
// Verify map is properly initialized before creating adapter
if (map.isStyleLoaded && map.isStyleLoaded()) {
// Safe to initialize Terra Draw
const draw = new TerraDraw({
adapter: new TerraDrawMapLibreGLAdapter({ map })
});
}
Debugging Tips¶
Enable Debug Mode¶
// Enable console logging for debugging
const draw = new TerraDraw({
adapter: new TerraDrawMapLibreGLAdapter({ map }),
modes: [new TerraDrawPointMode()],
debug: true // Enable debug mode if available
});
// Log all events for debugging
draw.on('*', (event) => {
console.log('Terra Draw event:', event);
});
Check Browser Console¶
Always check the browser console for errors:
- Open Developer Tools (F12)
- Check Console tab for errors
- Look for network errors in Network tab
- Check if all resources loaded correctly
Verify Feature Data¶
// Log feature data to understand structure
draw.on('change', () => {
const features = draw.getSnapshot();
console.log('Current features:', JSON.stringify(features, null, 2));
});
// Validate GeoJSON structure
const isValidGeoJSON = (feature: any) => {
return feature.type === 'Feature'
&& feature.geometry
&& feature.properties
&& feature.properties.mode;
};
Getting Help¶
Official Resources¶
- Documentation: Official Terra Draw Docs
- GitHub Repository: terra-draw
- GitHub Issues: Report bugs or ask questions
- Examples: Code examples
maplibre-gl-terradraw Resources¶
- Documentation: https://terradraw.water-gis.com
- GitHub Repository: maplibre-gl-terradraw
Community Support¶
- Discussions: Use GitHub Discussions for general questions
- Stack Overflow: Tag questions with
terra-draw
- MapLibre Community: MapLibre Slack
Reporting Issues¶
When reporting issues, include:
- Environment details: Browser, Node.js version, library versions
- Code example: Minimal reproducible code
- Error messages: Complete error logs from console
- Expected vs actual behavior: Clear description
- Screenshots: If UI-related
Example issue report template:
**Environment:**
- Browser: Chrome 120
- Terra Draw: 1.0.0
- MapLibre GL JS: 4.7.1
- Node.js: 22.0.0
**Issue:**
Features are not visible after drawing
**Code:**
[Minimal code example]
**Error:**
[Complete error message]
**Expected:**
Features should be visible on the map
**Actual:**
No features appear after drawing
Workshop Wrap-up¶
What We've Covered¶
- Environment Setup - Modern development with Vite and TypeScript
- Terra Draw Basics - Core concepts and first implementation
- Advanced Features - Custom styling, events, and data management
- MapLibre Integration - Using maplibre-gl-terradraw plugin
- Multi-library Support - Working with different mapping libraries
- Troubleshooting - Common issues and solutions
Key Takeaways¶
- Terra Draw provides a unified API across all major web mapping libraries
- The adapter pattern makes it easy to switch between mapping libraries
- Modern tooling like Vite and TypeScript improves developer experience
- Official documentation should always be your primary reference
- Community resources are available for additional support
Next Steps¶
- Experiment with different mapping libraries using Terra Draw
- Build a complete application using the patterns shown
- Contribute to the Terra Draw ecosystem
- Stay updated with new features and improvements
Resources for Continued Learning¶
- Official Documentation: jameslmilner.github.io/terra-draw/
- GitHub Repository: github.com/JamesLMilner/terra-draw
- maplibre-gl-terradraw: terradraw.water-gis.com
- Community: Join discussions and get help from other developers
Thank you for participating in the Terra Draw workshop at FOSS4G 2025 Auckland!