APIWebhooksAppsTeachfloor.jsAPI ReferenceGo to Teachfloor

Troubleshooting

Common issues and solutions for Teachfloor app development.

CLI Issues

"Not logged in" Error

Symptoms:

Error: Not logged in. Please run 'teachfloor login' first.

Solution:

teachfloor login

Enter your credentials and select your organization.

"Login failed: Request failed with status code 400"

Cause: OAuth client not properly configured

Solution:

  1. Check if API URL is correct:
echo $API_URL

  1. For self-hosted instances, ensure OAuth client is set up (see web-app/README.md)

  2. Contact platform administrator to configure OAuth client

"Invalid token" Error

Cause: Token expired or corrupted

Solution:

teachfloor logout
teachfloor login

"Not in app folder" Error

Symptoms:

Error: This command must be run inside a Teachfloor extension app folder.

Solution:

# Check for manifest file
ls teachfloor-app.json

# If not found, navigate to app folder
cd path/to/my-app

# Or create new app
teachfloor apps create my-app
cd my-app

CLI Command Not Found

Symptoms:

bash: teachfloor: command not found

Solution:

# Install globally
npm install -g @teachfloor/teachfloor-cli

# Verify installation
teachfloor version

# If still not found, check PATH
echo $PATH

# Use npx as alternative
npx @teachfloor/teachfloor-cli login

Build Issues

"npm run build" Fails

Symptoms:

Module not found: Error: Can't resolve...

Solution:

# Clear cache and reinstall
rm -rf node_modules
rm package-lock.json
npm install

# Clear webpack cache
rm -rf node_modules/.cache

# Try build again
npm run build

"Version already exists" Error

Symptoms:

Error: Version 1.0.0 is already approved.

Solution: Increment version in teachfloor-app.json: 

{
  "version": "1.0.1"
}

Then upload again:

teachfloor apps upload

Build Size Too Large

Symptoms: Warning about bundle size exceeding recommended limit

Solution:

# Analyze bundle
npm install --save-dev webpack-bundle-analyzer
ANALYZE=true npm run build

# Reduce size:
# 1. Remove unused dependencies
npm uninstall unused-package

# 2. Use dynamic imports
const Component = lazy(() => import('./Component'))

# 3. Minify images
# 4. Tree-shake imports
import { Button } from '@teachfloor/extension-kit' // ✅
import * as Kit from '@teachfloor/extension-kit'    // ❌

Runtime Issues

App Not Displaying

Checklist:

  1. Check viewport matches current page
  2. Verify app is installed
  3. Check browser console for errors
  4. Verify SDK is loading

Solution:

// Add debug logging
const { environment } = useExtensionContext()
console.log('Current viewport:', environment.viewport)
console.log('App initialized:', environment.initialized)

"Cannot read property of undefined"

Cause: Accessing context before initialization

Solution:

// ❌ Bad
const { userContext } = useExtensionContext()
return <div>{userContext.name}</div> // Error!

// ✅ Good
const { userContext, environment } = useExtensionContext()

if (!environment.initialized) {
  return <Loader />
}

return <div>{userContext.name}</div>

Data Not Persisting

Cause: Missing permissions or incorrect source

Solution:

  1. Check permissions in manifest:
{
  "permissions": [
    {
      "permission": "user_read",
      "purpose": "Display your profile"
    }
  ]
}
  1. Verify data source:
// Correct source
await store('key', data, 'userdata')  // ✅
await store('key', data, 'appdata')   // ✅

// Wrong source
await store('key', data, 'wrong')     // ❌
  1. Check for errors:
try {
  await store('key', data, 'userdata')
  console.log('Saved successfully')
} catch (error) {
  console.error('Save failed:', error)
}

Permission Denied Errors

Symptoms:

Error: Permission denied: user_read

Solution:

  1. Add permission to manifest:
teachfloor apps grant permission
  1. Upload new version:
teachfloor apps upload
  1. Users may need to reinstall app to approve new permissions

Development Issues

Hot Reload Not Working

Solution:

# Stop dev server (Ctrl+C)
# Clear cache
rm -rf node_modules/.cache

# Restart
teachfloor apps start

Port Already in Use

Symptoms:

Error: Port 3000 is already in use

Solution: Change port in webpack.config.js: 

module.exports = {
  devServer: {
    port: 3001, // Change port
  }
}

Or kill process using port:

# Find process
lsof -i :3000

# Kill process
kill -9 <PID>

Changes Not Reflecting

Solution:

# Hard refresh browser
Ctrl+Shift+R (Windows/Linux)
Cmd+Shift+R (Mac)

# Clear browser cache
# In DevTools: Right-click refresh → Empty Cache and Hard Reload

# Restart dev server
# Stop server (Ctrl+C)
teachfloor apps start

Manifest Issues

"Invalid manifest" Error

Cause: JSON syntax error or missing required fields

Solution:

# Validate JSON syntax
cat teachfloor-app.json | jq .

# Check required fields
jq '.id, .version, .name' teachfloor-app.json

# Common issues:
# - Missing comma
# - Extra comma
# - Unquoted strings
# - Wrong bracket type

Component Not Found

Symptoms:

Error: Cannot find module './MyView'

Solution:

  1. Check component name matches manifest:
{
  "ui_extension": {
    "views": [
      {
        "component": "MyView"  // Must match filename
      }
    ]
  }
}
  1. Verify file exists:
ls src/views/MyView.jsx
  1. Check export:
// Must use default export
export default MyView  // ✅
export { MyView }      // ❌

Browser Issues

Browser Console Errors

Common Errors:

  1. "Uncaught ReferenceError: tf is not defined"

    • SDK not loaded
    • Check public/index.html has SDK script

  2. "Cannot read property 'emit' of undefined"

    • Calling SDK before initialization
    • Wrap in useEffect with initialization check

  3. "Failed to fetch"

    • CORS issue or network error
    • Check API URL
    • Verify network connection

App Shows Blank Page

Debug Steps:

  1. Open browser console (F12)
  2. Check for JavaScript errors
  3. Verify platform is initialized:
import { useExtensionContext } from '@teachfloor/extension-kit'

const { environment } = useExtensionContext()
console.log('Initialized:', environment.initialized)
  1. Signal app is ready:
import { initialize } from '@teachfloor/extension-kit'

initialize()

Installation Issues

Cannot Install npm Packages

Solution:

# Clear npm cache
npm cache clean --force

# Delete lock file
rm package-lock.json

# Reinstall
npm install

# Try with legacy peer deps
npm install --legacy-peer-deps

Node Version Issues

Solution:

# Check version
node --version

# Should be 18.0.0 or higher
# Install/switch version
nvm install 20
nvm use 20

Deployment Issues

Upload Fails

Symptoms:

Error: Failed to upload app

Solution:

  1. Check authentication:
teachfloor whoami
  1. Verify network:
ping app.teachfloor.com
  1. Check manifest is valid
  2. Try again

Review Rejected

Common Reasons:

  • Unclear permission purposes
  • Security vulnerabilities
  • Poor user experience
  • Broken functionality
  • Missing documentation

Solution:

  1. Read rejection feedback carefully
  2. Fix identified issues
  3. Increment version
  4. Upload and resubmit

Performance Issues

App Loading Slowly

Solution:

// 1. Lazy load components
const HeavyComponent = lazy(() => import('./Heavy'))

// 2. Memoize expensive calculations
const result = useMemo(() => expensive(data), [data])

// 3. Debounce frequent operations
const debouncedFn = useMemo(
  () => debounce(fn, 500),
  []
)

// 4. Cache data
const cachedData = useMemo(() => data, [data])

High Memory Usage

Solution:

// Clean up timers and intervals
useEffect(() => {
  const timer = setTimeout(() => {
    // Do something
  }, 1000)

  return () => {
    clearTimeout(timer)  // Cleanup!
  }
}, [])

// Clear timers
useEffect(() => {
  const timer = setTimeout(() => {}, 1000)

  return () => {
    clearTimeout(timer)  // Cleanup!
  }
}, [])

Getting Help

Before Asking for Help

  1. Check browser console for errors
  2. Check CLI output for error messages
  3. Verify manifest is valid
  4. Check this troubleshooting guide
  5. Search GitHub issues

Where to Get Help

What to Include

When reporting issues:

  • Teachfloor CLI version (teachfloor version)
  • Node version (node --version)
  • Operating system
  • Full error message
  • Steps to reproduce
  • Manifest file (if relevant)
  • Console errors (screenshot)

Debug Mode

Enable Debug Logging

Add to public/index.html:

<script>
  window._tfOpts = {
    id: 'your-app-id',
    debug: true  // Enable debug mode
  }
</script>

This will log SDK events to console.

Common Mistakes

1. Not Handling Loading States 

// ❌ Bad
const { userContext } = useExtensionContext()
return <div>{userContext.name}</div>

// ✅ Good
const { userContext, environment } = useExtensionContext()
if (!environment.initialized) return <Loader />
return <div>{userContext.name}</div>

2. Not Handling Async Operations 

// ❌ Bad
useEffect(async () => {
  const data = await retrieve('key')
  setData(data)
}, [])

// ✅ Good
useEffect(() => {
  retrieve('key').then(setData)
}, [])

3. Over-Requesting Permissions 

// ❌ Bad - requesting everything
"permissions": [
  { "permission": "user_read", ... },
  { "permission": "user_events_read", ... },
  { "permission": "course_read", ... },
  // ... not all needed
]

// ✅ Good - only what's needed
"permissions": [
  { "permission": "course_read", "purpose": "Display course info" }
]

4. Not Validating Data 

// ❌ Bad
await store('data', userInput, 'userdata')

// ✅ Good
if (!isValid(userInput)) {
  throw new Error('Invalid input')
}
const sanitized = sanitize(userInput)
await store('data', sanitized, 'userdata')

Quick Reference

Reset Everything 

# Logout
teachfloor logout

# Clear cache
rm -rf node_modules/.cache
rm -rf dist/

# Reinstall
rm -rf node_modules
npm install

# Login again
teachfloor login

# Rebuild
npm run build

Debug Checklist 

□ Check browser console for errors
□ Verify environment.initialized is true
□ Check manifest is valid JSON
□ Confirm permissions are listed
□ Verify component files exist
□ Check SDK script is loaded
□ Confirm app is installed
□ Check viewport matches page
□ Verify data storage permissions
□ Test with hard refresh

Additional Resources